Authentication and Authorization
Overview
Authentication and authorization are two fundamental concepts in FusionAuth. The traditional definitions are:
-
authentication: who you are
-
authorization: what you can do
Authentication is sometimes referred to as authn
or AuthN
and authorization is sometimes referred to as authz
or AuthZ
.
Authentication in FusionAuth
Authentication means that a user has provided credentials which the system has accepted. This is often a username and password, but could be a code from a magic link, a token from a social auth provider, or a JWT from an external identity provider.
Authentication occurs with users, who are scoped to the tenant. When authentication happens, if you are using the Login API, a 2xx
response is returned from FusionAuth. See the API documentation for the specific 2xx
value. When using an Authorization Code grant, the user is redirected to the provided redirect_uri
.
In either case, the end result of the request will be a JWT containing information about the user. Here’s an example:
{
"aud": "469b0ba1-a849-4603-883e-3b05c0d2b7ce",
"authenticationType": "PASSWORD",
"email": "richard@fusionauth.io",
"exp": 1504112919754,
"iat": 1504103919754,
"iss": "acme.com",
"sub": "6558c73f-b345-4917-9aac-0feab21eeeeb"
}
Authorization in FusionAuth
Authorization means that the user has been registered with an application. Authentication is a necessary prerequisite to authorization; if FusionAuth doesn’t know who the user is, it can’t know what resources the user is allowed to access.
If using the Login API, the status code returned for an authorized user is typically 200
. See the API documentation for more details. When using an Authorization Code grant, the user is redirected to the provided redirect_uri
.
In either case, the end result of the request will be a JWT containing information about the user. Here’s an example:
{
"applicationId": "469b0ba1-a849-4603-883e-3b05c0d2b7ce",
"aud": "469b0ba1-a849-4603-883e-3b05c0d2b7ce",
"authenticationType": "PASSWORD",
"email": "richard@fusionauth.io",
"exp": 1504112919754,
"iat": 1504103919754,
"iss": "acme.com",
"roles": [
"role 1",
"role 2"
],
"sub": "6558c73f-b345-4917-9aac-0feab21eeeeb"
}
Authorization and Securing Your Application
These concepts are critical to application security.
If you are utilizing the JWT to authorize a user to your application, you must do more than just ensure the JWT has a valid signature and is not expired. You must also ensure the JWT has provided adequate claims to the user’s authorization.
If you enable "Require registration" on an application, the JWT won’t be provided until the user is registered for this application.
Checking the JWT signature and expiration are only a part of the story.
The aud
claim identifies the context of the request, in other words who is this JWT for: a Payroll application, a mobile application, etc. The presence of the applicationId
and roles
claims identifies the User’s registration (authorization) and access (roles) to the requested resource identified by the aud
claim.
An Example
Say Bob has access to applications A, B and C configured in FusionAuth, and Lisa has access to applications C, D and E. Assume there’s also an application F to which neither Bob nor Lisa is registered. Note that for this example to work all the applications A thru F have "Require registration" disabled (set to false
).
You grant access to a particular application with a User Registration. Once registered, a user can have 0 or more roles as defined by the Application.
Login results for Bob:
Bob --> Login to Application (A, B or C) --> [200] Authenticated
Bob --> Login to Application (D, E or F) --> [202] Authenticated not registered
Login results for Lisa:
Lisa --> Login to Application (A, B or F) --> [202] Authenticated not registered
Lisa --> Login to Application (C, D or E) --> [200] Authenticated
In addition to this status code, the JWT that is returned will not contain the applicationId
or the roles
claim because the user is not authorized for the requested resource.
In other words, FusionAuth has successfully authenticated the user because they exist, and the credentials they provided were correct. But if the user is not authorized to the Application, a 202
will be returned and the access token (JWT) returned will not contain authorization for the resource.
Feedback
How helpful was this page?
See a problem?
File an issue in our docs repo
Have a question or comment to share?
Visit the FusionAuth community forum.