ML API의 개발 및 생산화에 도움이 되는 몇 가지 흥미로운 새 기능을 제공하는 Flama 1.7의 최근 릴리스에 대해 이미 들어보셨을 것입니다. 이 게시물은 해당 릴리스의 주요 특징 중 하나인 JWT 인증 지원에 대해 정확하게 다루고 있습니다. 그러나 실제 사례를 통해 세부 사항을 살펴보기 전에 다음 리소스를 염두에 두는 것이 좋습니다(아직 숙지하지 않았다면 숙지하시기 바랍니다).
이제 새로운 기능을 시작하고 헤더나 쿠키를 통한 토큰 기반 인증으로 API 엔드포인트를 보호하는 방법을 살펴보겠습니다.
이 게시물의 구성은 다음과 같습니다.
JWT(JSON 웹 토큰)의 개념과 작동 방식에 이미 익숙하다면 이 섹션을 건너뛰고 바로 Flama를 사용하여 JWT 인증 구현하기로 이동하세요. 그렇지 않으면 JWT가 무엇인지, 인증 목적으로 왜 유용한지에 대한 간결한 설명을 제공하려고 노력할 것입니다.
RFC 7519 문서에 제공된 공식 정의부터 시작해 보겠습니다.
JSON 웹 토큰(JWT)은 URL에 안전한 소형 표현 수단입니다
두 당사자 간에 양도된다고 주장합니다. JWT의 주장
JSON의 페이로드로 사용되는 JSON 개체로 인코딩됩니다
웹 서명(JWS) 구조 또는 JSON 웹의 일반 텍스트
암호화(JWE) 구조를 통해 소유권 주장을 디지털화할 수 있습니다
메시지 인증 코드로 서명되었거나 무결성이 보호됨
(MAC) 및/또는 암호화됩니다.
간단히 말하면 JWT는 JSON 개체 형식으로 두 당사자 간에 정보를 전송하는 방법을 정의하는 개방형 표준입니다. 전송되는 정보는 무결성과 신뢰성을 보장하기 위해 디지털 서명됩니다. 이것이 JWT의 주요 사용 사례 중 하나가 인증 목적인 이유입니다.
전형적인 JWT 기반 인증 흐름은 다음과 같습니다.
그러나 JWT 토큰은 사용자를 식별하는 데 유용할 뿐만 아니라 토큰의 페이로드를 통해 안전한 방식으로 다양한 서비스 간에 정보를 공유하는 데에도 사용될 수 있습니다. 게다가 토큰의 서명이 헤더와 페이로드를 사용하여 계산되므로 수신자는 토큰의 무결성을 확인하고 전송 중에 변경되지 않았는지 확인할 수 있습니다.
JWT는 점(.)으로 구분된 일련의 URL 안전 부분으로 표시되며, 각 부분에는 base64url로 인코딩된 JSON 개체가 포함되어 있습니다. JWT의 부분 수는 사용되는 표현(JWS(JSON 웹 서명) RFC-7515 또는 JWE(JSON 웹 암호화) RFC-7516)에 따라 달라질 수 있습니다.
이 시점에서 우리는 JWT 토큰의 가장 일반적인 표현인 JWS를 사용할 것이라고 가정할 수 있습니다. 이 경우 JWT 토큰은 세 부분으로 구성됩니다.
따라서 평면화된 JWS JSON 직렬화를 사용하는 프로토타입 JWS JSON의 구문은 다음과 같습니다(자세한 내용은 RFC-7515 섹션 7.2.2 참조).
{
"payload":"<payload contents>",
"header":<header contents>,
"signature":"<signature contents>"
}
JWS Compact Serialization에서 JTW는 연결로 표시됩니다.
BASE64URL(UTF8(JWS Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)
JWT 토큰의 예는 다음과 같습니다(여기 Flama 테스트 중 하나에서 가져옴).
eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJkYXRhIjogeyJmb28iOiAiYmFyIn0sICJpYXQiOiAwfQ==.J3zdedMZSFNOimstjJat0V28rM_b1UU62XCp9dg_5kg=
일반 JWT 객체의 경우 헤더에는 JWT가 JWS인지 JWE인지에 따라 다양한 필드(예: 토큰에 적용되는 암호화 작업 설명)가 포함될 수 있습니다. 그러나 두 경우 모두에 공통적이고 가장 일반적으로 사용되는 일부 필드가 있습니다.
The payload contains the claims (information) that the token is carrying. The claims are represented as a JSON object, and they can be divided into three categories, according to the standard RFC-7519 Sec. 4:
The signature is used to ensure the integrity of the token and to verify that the sender of the token is who it claims to be. The signature is calculated using the header and the payload, and it is generated using the algorithm specified in the header. The signature is then appended to the token to create the final JWT.
Having introduced the concept of JWT, its potential applications, besides a prototypical authentication flow, we can now move on to the implementation of a JWT-authenticated API using Flama. But, before we start, if you need to review the basics on how to create a simple API with flama, or how to run the API once you already have the code ready, then you might want to check out the quick start guide. There, you'll find the fundamental concepts and steps required to follow this post. Now, without further ado, let's get started with the implementation.
Our first step is to create our development environment, and install all required dependencies for this project. The good thing is that for this example we only need to install flama to have all the necessary tools to implement JWT authentication. We'll be using poetry to manage our dependencies, but you can also use pip if you prefer:
poetry add flama[full]
If you want to know how we typically organise our projects, have a look at our previous post here, where we explain in detail how to set up a python project with poetry, and the project folder structure we usually follow.
Let's start with a simple application that has a single public endpoint. This endpoint will return a brief description of the API.
from flama import Flama
app = Flama(
title="JWT protected API",
version="1.0.0",
description="JWT Authentication with Flama ?",
docs="/docs/",
)
@app.get("/public/info/", name="public-info")
def info():
"""
tags:
- Public
summary:
Ping
description:
Returns a brief description of the API
responses:
200:
description:
Successful ping.
"""
return {"title": app.schema.title, "description": app.schema.description, "public": True}
If you want to run this application, you can save the code above in a file called main.py under the src folder, and then run the following command (remember to have the poetry environment activated, otherwise you'll need to prefix the command with poetry run):
flama run --server-reload src.main:app INFO: Started server process [3267] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
where the --server-reload flag is optional and is used to reload the server automatically when the code changes. This is very useful during development, but you can remove it if you don't need it. For a full list of the available options, you can run flama run --help, or check the documentation.
Ok, now that we have our base application running, let's add a new endpoint that requires authentication. To do this, we'll need to use the following flama functionality:
Let's proceed and modify our base application to include the JWT authentication as intended, and then we'll explain the code in more detail.
import uuid
from flama import Flama
from flama.authentication import AuthenticationMiddleware, JWTComponent
from flama.middleware import Middleware
JWT_SECRET_KEY = uuid.UUID(int=0).bytes # The secret key used to signed the token
JWT_HEADER_KEY = "Authorization" # Authorization header identifie
JWT_HEADER_PREFIX = "Bearer" # Bearer prefix
JWT_ALGORITHM = "HS256" # Algorithm used to sign the token
JWT_TOKEN_EXPIRATION = 300 # 5 minutes in seconds
JWT_REFRESH_EXPIRATION = 2592000 # 30 days in seconds
JWT_ACCESS_COOKIE_KEY = "access_token"
JWT_REFRESH_COOKIE_KEY = "refresh_token"
app = Flama(
title="JWT-protected API",
version="1.0.0",
description="JWT Authentication with Flama ?",
docs="/docs/",
)
app.add_component(
JWTComponent(
secret=JWT_SECRET_KEY,
header_key=JWT_HEADER_KEY,
header_prefix=JWT_HEADER_PREFIX,
cookie_key=JWT_ACCESS_COOKIE_KEY,
)
)
app.add_middleware(
Middleware(AuthenticationMiddleware),
)
# The same code as before here
# ...
Although we've decided to add the component and middleware after the initialisation of the app, you can also add them directly to the Flama constructor by passing the components and middlewares arguments:
app = Flama(
title="JWT-protected API",
version="1.0.0",
description="JWT Authentication with Flama ?",
docs="/docs/",
components=[
JWTComponent(
secret=JWT_SECRET_KEY,
header_key=JWT_HEADER_KEY,
header_prefix=JWT_HEADER_PREFIX,
cookie_key=JWT_ACCESS_COOKIE_KEY,
)
],
middlewares=[
Middleware(AuthenticationMiddleware),
]
)
This is just a matter of preference, and both ways are completely valid.
With the modifications introduced above, we can proceed to add a new (and JWT protected) endpoint. However, before we do that, let's briefly explain in more detail the functionality we've just introduced, namely components and middlewares.
As you might've already noticed, whenever we create a new application we're instantiating a Flama object. As the application grows, as is the case right now, also grows the need to add more dependencies to it. Without dependency injection (DI), this would mean that the Flama class would have to create and manage all its dependencies internally. This would make the class tightly coupled to specific implementations and harder to test or modify. With DI the dependencies are provided to the class from the outside, which decouples the class from specific implementations, making it more flexible and easier to test. And, this is where components come into play in flama.
In flama, a Component is a building block for dependency injection. It encapsulates logic that determines how specific dependencies should be resolved when the application runs. Components can be thought of as self-contained units responsible for providing the necessary resources that the application's constituents need. Each Component in flama has a unique identity, making it easy to look up and inject the correct dependency during execution. Components are highly flexible, allowing you to handle various types of dependencies, whether they're simple data types, complex objects, or asynchronous operations. There are several built-in components in flama, although in this post we're going to exclusively focus on the JWTComponent, which (as all others) derives from the Component class.
The JWTComponent contains all the information and logic necessary for extracting a JWT from either the headers or cookies of an incoming request, decoding it, and then validating its authenticity. The component is initialised with the following parameters:
In the code above, we've initialised the JWTComponent with some dummy values for the secret key, header key, header prefix, and cookie key. In a real-world scenario, you should replace these values with your own secret key and identifiers.
Middleware is a crucial concept that acts as a processing layer between the incoming requests from clients and the responses sent by the server. In simpler terms, middleware functions as a gatekeeper or intermediary that can inspect, modify, or act on requests before they reach the core logic of your application, and also on the responses before they are sent back to the client.
In flama, middleware is used to handle various tasks that need to occur before a request is processed or after a response is generated. In this particular case, the task we want to handle is the authentication of incoming requests using JWT. To achieve this, we're going to use the built-in class AuthenticationMiddleware. This middleware is designed to ensure that only authorised users can access certain parts of your application. It works by intercepting incoming requests, checking for the necessary credentials (such as a valid JWT token), and then allowing or denying access based on the user's permissions which are encoded in the token.
Here’s how it works:
By now, we should have a pretty solid understanding on what our code does, and how it does it. Nevertheless, we still need to see what we have to do to add a protected endpoint to our application. Let's do it:
@app.get("/private/info/", name="private-info", tags={"permissions": ["my-permission-name"]})
def protected_info():
"""
tags:
- Private
summary:
Ping
description:
Returns a brief description of the API
responses:
200:
description:
Successful ping.
"""
return {"title": app.schema.title, "description": app.schema.description, "public": False}
And that's it! We've added a new endpoint that requires authentication to access. The functionality is exactly the same as the previous endpoint, but this time we've added the tags parameter to the @app.get decorator. The tag parameter can be used to specify additional metadata for an endpoint. But, if we use the special key permissions whilst using the AuthenticationMiddleware, we can specify the permissions required to access the endpoint. In this case, we've set the permissions to ["my-permission-name"], which means that only users with the permission my-permission-name will be able to access this endpoint. If a user tries to access the endpoint without the required permission, they will receive a 403 Forbidden response.
If we put all the pieces together, we should have a fully functional application that has a public endpoint and a private endpoint that requires authentication. The full code should look something like this:
import uuid
from flama import Flama
from flama.authentication import AuthenticationMiddleware, JWTComponent
from flama.middleware import Middleware
JWT_SECRET_KEY = uuid.UUID(int=0).bytes # The secret key used to signed the token
JWT_HEADER_KEY = "Authorization" # Authorization header identifie
JWT_HEADER_PREFIX = "Bearer" # Bearer prefix
JWT_ALGORITHM = "HS256" # Algorithm used to sign the token
JWT_TOKEN_EXPIRATION = 300 # 5 minutes in seconds
JWT_REFRESH_EXPIRATION = 2592000 # 30 days in seconds
JWT_ACCESS_COOKIE_KEY = "access_token"
JWT_REFRESH_COOKIE_KEY = "refresh_token"
app = Flama(
title="JWT-protected API",
version="1.0.0",
description="JWT Authentication with Flama ?",
docs="/docs/",
)
app.add_component(
JWTComponent(
secret=JWT_SECRET_KEY,
header_key=JWT_HEADER_KEY,
header_prefix=JWT_HEADER_PREFIX,
cookie_key=JWT_ACCESS_COOKIE_KEY,
)
)
app.add_middleware(
Middleware(AuthenticationMiddleware),
)
@app.get("/public/info/", name="public-info")
def info():
"""
tags:
- Public
summary:
Info
description:
Returns a brief description of the API
responses:
200:
description:
Successful ping.
"""
return {"title": app.schema.title, "description": app.schema.description, "public": True}
@app.get("/private/info/", name="private-info", tags={"permissions": ["my-permission-name"]})
def protected_info():
"""
tags:
- Private
summary:
Info
description:
Returns a brief description of the API
responses:
200:
description:
Successful ping.
"""
return {"title": app.schema.title, "description": app.schema.description, "public": False}
Running the application as before, we should see the following output:
flama run --server-reload src.main:app INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) INFO: Started reloader process [48145] using WatchFiles INFO: Started server process [48149] INFO: Waiting for application startup. INFO: Application startup complete.
If we navigate with our favourite browser to http://127.0.0.1:8000/docs/ we should see the documentation of our API as shown below:
As we can already expect, if we send a request to the public endpoint /public/info/ we should receive a successful response:
curl --request GET \
--url http://localhost:8000/public/info/ \
--header 'Accept: application/json'
{"title":"JWT protected API","description":"JWT Authentication with Flama ?","public":true}
However, if we try to access the private endpoint /private/info/ without providing a valid JWT token, we should receive a 401 Unauthorized response:
curl --request GET \
--url http://localhost:8000/private/info/ \
--header 'Accept: application/json'
{"status_code":401,"detail":"Unauthorized","error":null}%
Thus, we can say that the JWT authentication is working as expected, and only users with a valid JWT token will be able to access the private endpoint.
As we've just seen, we have a private endpoint which requires a valid JWT token to be accessed. But, how do we get this token? The answer is simple: we need to create a login endpoint that will authenticate the user and return a valid JWT token. To do this, we're going to define the schemas for the input and output of the login endpoint (feel free to use your own schemas if you prefer, for instance, adding more fields to the input schema such as username or email):
import uuid
import typing
import pydantic
class User(pydantic.BaseModel):
id: uuid.UUID
password: typing.Optional[str] = None
class UserToken(pydantic.BaseModel):
id: uuid.UUID
token: str
Now, let's add the login endpoint to our application:
import http
from flama import types
from flama.authentication.jwt import JWT
from flama.http import APIResponse
@app.post("/auth/", name="signin")
def signin(user: types.Schema[User]) -> types.Schema[UserToken]:
"""
tags:
- Public
summary:
Authenticate
description:
Returns a user token to access protected endpoints
responses:
200:
description:
Successful ping.
"""
token = (
JWT(
header={"alg": JWT_ALGORITHM},
payload={
"iss": "vortico",
"data": {"id": str(user["id"]), "permissions": ["my-permission-name"]},
},
)
.encode(JWT_SECRET_KEY)
.decode()
)
return APIResponse(
status_code=http.HTTPStatus.OK, schema=types.Schema[UserToken], content={"id": str(user["id"]), "token": token}
)
In this code snippet, we've defined a new endpoint /auth/ that receives a User object as input and returns a UserToken object as output. The User object contains the id of the user and the password (which is optional for this example, since we're not going to be comparing it with any stored password). The UserToken object contains the id of the user and the generated token that will be used to authenticate the user in the private endpoints. The token is generated using the JWT class, and contains the permissions granted to the user, in this case, the permission my-permission-name, which will allow the user to access the private endpoint /private/info/.
Now, let's test the login endpoint to see if it's working as expected. For this, we can proceed via the /docs/ page:
Or, we can use curl to send a request to the login endpoint:
curl --request POST \
--url http://localhost:8000/auth/ \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"password": "string"
}'
which should return a response similar to this:
{"id":"497f6eca-6276-4993-bfeb-53cbbbba6f08","token":"eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJkYXRhIjogeyJpZCI6ICI0OTdmNmVjYS02Mjc2LTQ5OTMtYmZlYi01M2NiYmJiYTZmMDgiLCAicGVybWlzc2lvbnMiOiBbIm15LXBlcm1pc3Npb24tbmFtZSJdfSwgImlhdCI6IDE3MjU5ODk5NzQsICJpc3MiOiAidm9ydGljbyJ9.vwwgqahgtALckMAzQHWpNDNwhS8E4KAGwNiFcqEZ_04="}
That string is the JWT token that we can use to authenticate the user in the private endpoint. Let's try to access the private endpoint using the token:
curl --request GET \ --url http://localhost:8000/private/info/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJkYXRhIjogeyJpZCI6ICI0OTdmNmVjYS02Mjc2LTQ5OTMtYmZlYi01M2NiYmJiYTZmMDgiLCAicGVybWlzc2lvbnMiOiBbIm15LXBlcm1pc3Npb24tbmFtZSJdfSwgImlhdCI6IDE3MjU5ODk5NzQsICJpc3MiOiAidm9ydGljbyJ9.vwwgqahgtALckMAzQHWpNDNwhS8E4KAGwNiFcqEZ_04='
which now returns a successful response:
{"title":"JWT protected API","description":"JWT Authentication with Flama ?","public":false}
And that's it! We've successfully implemented JWT authentication in our Flama application. We now have a public endpoint that can be accessed without authentication, a private endpoint that requires a valid JWT token to be accessed, and a login endpoint that generates a valid JWT token for the user.
The privatisation of some endpoints (even all at some instances) is a common requirement in many applications, even more so when dealing with sensitive data as is often the case in Machine Learning APIs which process personal or financial information, to name some examples. In this post, we've covered the fundamentals of token-based authentication for APIs, and how this can be implemented without much of a hassle using the new features introduced in the latest release of flama (introduced in a previous post). Thanks to the JWTComponent and AuthenticationMiddleware, we can secure our API endpoints and control the access to them based on the permissions granted to the user, and all this with just a few modifications to our base unprotected application.
We hope you've found this post useful, and that you're now ready to implement JWT authentication in your own flama applications. If you have any questions or comments, feel free to reach out to us. We're always happy to help!
Stay tuned for more posts on flama and other exciting topics in the world of AI and software development. Until next time!
If you like what we do, there is a free and easy way to support our work. Gift us a ⭐ at Flama.
GitHub ⭐'s mean a world to us, and give us the sweetest fuel to keep working on it to help others on its journey to build robust Machine Learning APIs.
You can also follow us on ?, where we share our latest news and updates, besides interesting threads on AI, software development, and much more.
위 내용은 Flama JWT 인증으로 보호되는 ML API의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!
![[웹 프런트엔드] Node.js 빠른 시작](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
