Authentication and Authorization

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.