Como Implementar Autenticação e Autorização com OAuth2 no FastAPI

A segurança nas APIs é uma preocupação central para qualquer desenvolvedor. O uso do OAuth2 para autenticação e autorização é uma abordagem altamente eficaz e amplamente adotada, especialmente quando se trata de proteger endpoints em aplicações web. O FastAPI, framework moderno e robusto para construção de APIs, facilita esse processo com sua integração nativa ao OAuth2. Nesta seção, vamos explorar como você pode implementar autenticação segura em sua API com o FastAPI utilizando o padrão OAuth2, abordando a configuração de endpoints, a geração de tokens e a verificação da autorização do usuário.

python
Copy code
from fastapi import Depends, HTTPException
from fastapi.security import OAuth2PasswordRequestForm
from security import UserInDB, fake_token_generator, fakely_hash_password, fake_users_db
@app.post("/token")

async def login(form_data: OAuth2PasswordRequestForm = Depends()):

    user_dict = fake_users_db.get(form_data.username)
    if not user_dict:
        raise HTTPException(
            status_code=400, 
            detail="Incorrect username or password"
        )
    user = UserInDB(**user_dict)
    hashed_password = fakely_hash_password(form_data.password)
    if not hashed_password == user.hashed_password:
        raise HTTPException(
            status_code=400, 
            detail="Incorrect username or password"
        )
    token = fake_token_generator(user)
    return {
        "access_token": token,
        "token_type": "bearer"
    }

Neste código, quando o usuário envia um nome de usuário e senha corretos, o sistema gera um token de acesso que é enviado de volta ao usuário. Esse token será usado para autenticar o usuário em outros endpoints da API. No exemplo seguinte, mostramos como proteger um endpoint que requer o token de acesso:

python
Copy code
from security import get_user_from_token

@app.get("/users/me", response_model=User)
def read_users_me(current_user: User = Depends(get_user_from_token)):
    return current_user

Aqui, o endpoint /users/me está protegido. Apenas usuários que fornecerem um token válido terão acesso a ele. A função get_user_from_token valida o token, garantindo que o usuário que está fazendo a solicitação seja autorizado.

Além disso, o OAuth2 oferece a possibilidade de definir "escopos" para controlar o nível de acesso concedido ao usuário. Cada escopo pode definir ações ou recursos específicos que o cliente tem permissão para acessar em nome do usuário. Embora o FastAPI facilite a implementação de escopos, isso vai além do escopo desta seção. Para mais detalhes sobre como definir e usar escopos em uma aplicação FastAPI, consulte a documentação oficial do FastAPI.

Outro aspecto importante da segurança em APIs é a capacidade de personalizar a documentação gerada automaticamente pelo FastAPI. A documentação, acessível nas URLs /docs e /redoc, oferece uma interface interativa que permite aos usuários testar os endpoints da API diretamente. É possível customizar essa documentação, ocultando endpoints sensíveis como o de login (/token) ou alterando o título, descrição e versão da API. A personalização da documentação pode ser feita da seguinte forma:

python
Copy code
from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Customized Title",
        version="2.0.0",
        description="This is a custom OpenAPI schema",
        routes=app.routes,
    )
    del openapi_schema["paths"]["/token"]
    app.openapi_schema = openapi_schema
    return app.openapi_schema
app = FastAPI(
    title="Task Manager API",
    description="This is a task management API",
    version="0.1.0",
)
app.openapi = custom_openapi

Ao usar esse método, podemos garantir que informações sensíveis ou desnecessárias não sejam expostas na documentação pública.

Além das funcionalidades básicas de autenticação e autorização, é crucial que o desenvolvedor esteja ciente de algumas boas práticas quando se trabalha com segurança em APIs. É sempre recomendável que os tokens sejam armazenados de forma segura e que se implementem estratégias de renovação de tokens, caso o acesso seja prolongado. A utilização de HTTPS para garantir a criptografia dos dados em trânsito também é essencial.

Além disso, sempre que possível, deve-se aplicar o princípio de menor privilégio, ou seja, conceder ao usuário apenas os acessos necessários para a execução de suas tarefas. Isso pode ser feito por meio de escopos e permissões rigorosas, evitando assim que dados sensíveis sejam acessados por usuários não autorizados.

Como Organizar e Criar Endpoints com FastAPI

No desenvolvimento de APIs, uma das etapas mais importantes é a criação de endpoints. FastAPI facilita esse processo com sua abordagem intuitiva e funcional. A maneira como o código é estruturado, através de routers e endpoints, contribui significativamente para a manutenção e clareza do projeto. Neste capítulo, abordaremos como construir e organizar endpoints e routers, além de como usar FastAPI para criar e gerenciar um servidor com documentação automática.

Os endpoints são os pontos de interação da API com o usuário. Em FastAPI, um endpoint é criado ao decorar uma função com um método HTTP, como o @app.get("/route"), indicando que a função responderá a requisições GET para aquele caminho. Por exemplo, considere o seguinte código simples que cria um endpoint para a raiz da aplicação:

python
Copy code
from fastapi import FastAPI

app = FastAPI()
@app.get("/")
async def read_root():
    return {"Hello": "World"}

Quando um pedido GET é feito para a raiz da aplicação ("/"), a função read_root é chamada, retornando uma resposta JSON. A simplicidade desse exemplo ilustra a clareza e a eficácia da estruturação de endpoints com FastAPI.

Organizando com Routers

À medida que o projeto cresce, a necessidade de organizar o código torna-se evidente. Para lidar com múltiplos endpoints, principalmente quando estão distribuídos por diferentes arquivos, o uso de routers é fundamental. Eles permitem agrupar funcionalidades específicas em módulos separados, facilitando a manutenção e compreensão do código.

python
Copy code
from fastapi import APIRouter
router = APIRouter()
@router.get("/items/{item_id}")

async def read_item(item_id: int):

    return {"item_id": item_id}

Este código define um endpoint que aceita requisições GET na rota /items/{item_id}. O parâmetro item_id é capturado da URL e passado para a função, que retorna um objeto JSON. Para incluir este router na aplicação principal, basta registrá-lo com o método include_router():

python
Copy code
import router_example

from fastapi import FastAPI
app = FastAPI()
app.include_router(router_example.router)
@app.get("/")
async def read_root():
    return {"Hello": "World"}

Esse exemplo demonstra como você pode modularizar sua API e tornar o código mais limpo e organizado. Quando seu projeto evolui e novos endpoints são adicionados, você poderá criar múltiplos routers para diferentes funcionalidades e agrupá-los conforme necessário.

Executando o Servidor FastAPI

Com o FastAPI configurado, é hora de rodar o servidor. Para isso, usamos o Uvicorn, um servidor ASGI (Asynchronous Server Gateway Interface). Se seu arquivo principal se chama main.py e sua instância FastAPI é chamada app, você pode iniciar o servidor com o seguinte comando:

bash
Copy code
$ uvicorn main:app --reload

O parâmetro --reload é essencial durante o desenvolvimento, pois permite que o servidor seja recarregado automaticamente sempre que o código for alterado, sem a necessidade de reiniciar manualmente.

Após o servidor ser iniciado, sua API estará acessível em http://127.0.0.1:8000. Ao acessar esta URL no navegador, você verá a resposta JSON definida no endpoint raiz.

Documentação Automática

• Swagger UI: http://127.0.0.1:8000/docs

• Redoc: http://127.0.0.1:8000/redoc

Essas interfaces permitem que você visualize, explore e até mesmo teste os endpoints diretamente do navegador, facilitando o desenvolvimento e a comunicação sobre a API. O Swagger UI, por exemplo, apresenta uma forma interativa de enviar requisições e visualizar as respostas de maneira dinâmica.

Tipos de Parâmetros e Validação Automática

Ao criar endpoints, é comum que seja necessário trabalhar com parâmetros que variam de acordo com a requisição do usuário. Em FastAPI, você pode lidar com dois tipos de parâmetros: path parameters e query parameters.

• Path parameters são usados diretamente na URL, como no caso de /books/{book_id}. O FastAPI automaticamente captura o valor do parâmetro e o passa para a função que manipula a requisição.

• Query parameters, por sua vez, são usados após o ponto de interrogação na URL, como em /books/?author=Fitzgerald. Esses parâmetros são acessíveis diretamente através dos parâmetros da função.

Testando a API

Além das interfaces de documentação, há outras ferramentas que podem ser utilizadas para testar a API. Uma das mais populares é o Postman, um cliente de API que oferece uma maneira robusta de enviar requisições, testar e documentar a API. No Postman, você pode facilmente configurar uma requisição GET para testar seus endpoints, fornecendo uma URL como http://127.0.0.1:8000/books/1.

Conclusão

Com o que foi abordado até aqui, já é possível construir e organizar endpoints básicos em FastAPI, utilizando boas práticas como o uso de routers para modularizar o código. A simplicidade do FastAPI, junto com suas funcionalidades de validação de dados e documentação automática, facilita imensamente o processo de criação de APIs robustas e escaláveis. O uso de ferramentas como Swagger UI e Postman também melhora a experiência de desenvolvimento e testes.

Como Utilizar Parâmetros de Caminho e Consultas com FastAPI para Criar APIs Eficientes

No desenvolvimento de APIs, a definição e a manipulação de parâmetros desempenham um papel fundamental na construção de sistemas robustos e flexíveis. O FastAPI, um framework de Python, torna esse processo especialmente eficiente e direto, oferecendo ferramentas poderosas como parâmetros de caminho e consultas, que permitem a customização das respostas dos endpoints. Ao mesmo tempo, a integração com o Pydantic facilita a validação de dados, garantindo que as informações trocadas entre cliente e servidor estejam bem estruturadas e sejam seguras.

Considerando um exemplo prático, temos o seguinte endpoint simples para buscar informações sobre um autor em nossa API:

python
Copy code
@app.get("/authors/{author_id}")

async def read_author(author_id: int):

    return {
        "author_id": author_id,
        "name": "Ernest Hemingway"
    }

Neste caso, o author_id é um parâmetro de caminho. Quando um usuário solicita um recurso específico, como o autor identificado por um número, o FastAPI usa o parâmetro author_id da URL para personalizar a resposta. O valor do parâmetro é extraído diretamente da URL, permitindo que o cliente obtenha a informação desejada.

Além dos parâmetros de caminho, os parâmetros de consulta (query parameters) são outra ferramenta essencial para refinar a resposta da API. Eles são adicionados após o símbolo de interrogação (?) na URL e podem ser utilizados para filtrar ou modificar o conteúdo retornado pela API. Um exemplo típico é o uso de parâmetros de consulta para filtrar os livros por ano de publicação:

python
Copy code
@app.get("/books")

async def read_books(year: int = None):
    if year:
        return {
            "year": year,
            "books": ["Book 1", "Book 2"]
        }
    return {"books": ["All Books"]}

A combinação de parâmetros de caminho e de consulta permite construir APIs mais dinâmicas e adaptáveis, facilitando a filtragem e a manipulação dos dados. Mas a personalização das respostas não se limita apenas à utilização de parâmetros. Outra etapa importante é a definição de modelos de requisição e resposta com o auxílio do Pydantic, uma biblioteca que permite validar e estruturar os dados trocados entre o cliente e o servidor.

No exemplo a seguir, vemos como definir um modelo de livro usando Pydantic:

python
Copy code
from pydantic import BaseModel
class Book(BaseModel):
    title: str
    author: str
    year: int

Além de validar dados de entrada, o FastAPI também permite definir explicitamente o formato das respostas. Por exemplo, ao retornar informações sobre livros, podemos optar por omitir campos específicos ou modificar a estrutura dos dados antes de enviá-los ao cliente:

python
Copy code
class BookResponse(BaseModel):
    title: str
    author: str
@app.get("/allbooks")

async def read_all_books() -> list[BookResponse]:

    return [
        {"title": "1984", "author": "George Orwell"},

        {"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}

    ]

No código acima, a resposta de /allbooks inclui apenas o título e o autor dos livros, omitindo o ano de publicação. Isso é útil para proteger dados sensíveis ou para reduzir a quantidade de informações desnecessárias retornadas em uma consulta.

Além disso, o FastAPI permite o uso de tipos de resposta explícitos, como response_model, que ajuda a garantir que a resposta do servidor esteja de acordo com o formato definido pelo modelo. Ao usar o response_model, é possível também transformar dados antes de enviá-los ao cliente, o que proporciona maior controle sobre o formato da resposta e a segurança dos dados.

Outro aspecto essencial no desenvolvimento de APIs robustas e confiáveis é o tratamento de erros. FastAPI fornece uma abordagem integrada para lidar com exceções e erros de forma eficiente, garantindo que o sistema responda de maneira clara e útil para o cliente em caso de problemas. Ao definir os modelos de resposta e utilizar o Pydantic, conseguimos também estruturar os erros de maneira consistente, com mensagens detalhadas sobre o que ocorreu de errado.