OAuth authorization & OIDC authentication

The OAuth 2.0 authorization framework is a protocol that allows you to authorize a third-party web site or application access to your protected resources, without necessarily revealing your long-term credentials or even your identity. For example, when users access your application, they can log in with their Google account.

There are two distinct processes involved when allowing a user to enter a network and use a particular application: authentication and authorization.

OAuth is an open standard for authorization. It provides third-party applications with limited access to secure resources without compromising the user’s data or credentials.

OpenID Connect (OIDC) is an authentication protocol that verifies a user's identity when a user tries to access some resources. OIDC was developed to work together with OAuth by providing an authentication layer to support the authorization layer provided by OAuth.

OAuth access token

The access token generated by OAuth does not contain any identifiable information on the user. Access tokens exist to authorize access to resources, such as applications and servers, on a limited basis.

Access tokens can be acquired in several ways without human involvement. For example, when an original access token is invalidated, the client can exchange it for another token, called a refresh token. This automatic exchange between machines does not involve the user verifying their identity—and so access tokens are not proof of authentication.

OIDC ID token

OIDC introduces authentication to OAuth by including additional components, such as an ID token, which is issued as a JSON Web Token (JWT). ID tokens are the defining component of the OIDC protocol. Think of ID tokens as ID cards—they are digitally signed (JWS), generated for a particular client, can include requested details such as the user's name, email address, and birthdate, and they can be encrypted (JWE).

An ID token is evidence of authentication; an access token is not. This is because ID tokens can only be obtained when the user explicitly gives a client access to whatever information it requests and requires, such as "Sign in with Facebook."

For enhanced security measures, it is strongly recommended to utilize OAuth authorization in conjunction with OIDC.

FortiWeb supports OAuth 2.0 for front-end authentication, and it works as an authorization client or a resource server. The authorization process works as below.

When FortiWeb works as an authorization client:

1. Users initiate the access request to FortiWeb.
2. FortiWeb returns the OAuth login page.
3. User chooses an OAuth provider.
4. FortiWeb redirects the access request to the third party Authentication Server.
5. The third party Authentication Server performs the authentication and authorization interactions, then redirects the access request back to FortiWeb with an authorization code. The access token and ID token will be obtained in the code.
6. FortiWeb redirects user to the original URL with cookie.
7. User accesses the URL with cookie, and the access token and ID token should be refreshed before it expires.
8. If authentication failure occurs, FortiWeb returns error page to the user.
   

When FortiWeb works as a resource server:

1. Users initiate the access request to FortiWeb.
2. FortiWeb extracts token from Authorization header, then validates the token with the third party Authentication Server to confirm this is a legitimate user and try to get the username. If valid, FortiWeb forwards the request to the back-end server. If invalid, will return error page to the user.

OAuth 2.0 Authorization on FortiWeb requires you to configure OAuth servers and server pool, then select this server pool in a site publish rule.

Step 1 - Creating an OAuth server

Perform the following steps to create OAuth requests:

1. Go to User > OAuth Server, Select the OAuth Request tab.
2. FortiWeb has pre-defined the commonly seen Google, Facebook, FortiAuthenticator, and Okta OAuth requests for user authentication.
   You can Create New or click Clone to clone a request so that you can tailor it according to your needs. Configure the following settings.

   Name	Enter a name for the request.
   Request Type	OAuth request types, including: authorization (default) token refresh validation userinfo To implement OAuth authorization, it is necessary to create separate requests for each of the request type. Therefore, a total of 5 requests need to be created. The JWKS request type is for OIDC authentication. We will introduce it in later steps.
   Endpoint	OAuth request URL.
   TLS Check	Enable to do strict TLS verification even with a custom CA certificate to check the TLS traffic between FortiWeb and the third party OAuth authorization servers.
   TLS CA Certficate	Select the certificate to check the TLS traffic. It's uploaded in System > Admin > Certificates.
   Method	Request method: get (default) post
   User Key	Indicate username keyword in response.
   Content type	Select the request content type.
   Custom Headers	Enter the header name and value.
   Custom Parameters	Enter the parameter name and value.

3. Click OK.
4. Create additional requests to cover all the 5 request types.
5. Optional. If you want to leverage OAuth authorization in combination with OIDC authentication, you will need to create a request to obtain the JWKS (JSON Web Key Set). The Request Type should be JWKS.
6. Go to User > OAuth Server, Select the OAuth Server tab. Click Create New or click Clone to clone a server configuration so that you can tailor it. Configure the following settings.
   

   Name	Enter a name for the server.
   Mode	Select whether FortiWeb works as an authorization client or a resource server, or both.
   Scope	Enter the scope field for OAuth.
   OpenID Connect	Enable to use OIDC authentication. If OpenID Connect is enabled, you should select openid in the Scope option.
   Client ID/Client Secret	A client credential. Assigned by authorization server.
   Redirection Endpoint	Redirection URL back to FortiWeb.
   Authorization Request	The authorization request created in the OAuth Request tab.
   Token Request	The token request created in the OAuth Request tab.
   Refresh Request	The refresh request created in the OAuth Request tab.
   Valid Request	The valid request created in the OAuth Request tab.
   User Info. Request	The user info request created in the OAuth Request tab.
   JWKS Request	The JWKS request created in the OAuth Request tab. Available only if OpenID Connect is enabled.

Step 2 - Creating an OAuth Server pool

1. Go to Application Delivery > Site Publish > OAuth Server pool.
2. Click Create New.
3. Enter a name for the server pool.
4. Select whether the server works in Client mode or Resource Server mode, or both.
   If you choose the resource server mode, please make sure you have a device in front of FortiWeb to do the interaction with third party Authentication Server.
5. Click OK.
6. Click Create New to add server in the pool.
7. Enter a name for the OAuth server, then select the server you have created in Step 1 - Creating an OAuth server.
8. Click OK.

Step 3 - Creating a Site Publish rule for OAuth Authentication

1. Go to Application Delivery > Site Publish > Site Publish.
2. Refer to Offloaded authentication and optional SSO configuration for how to create a Site Publish rule and policy. For the Client Authentication Method, select OAuth Authentication; For OAuth Server Pool, select the OAuth server pool you have created.

Step 4 - Creating an authentication page

1. Go to System > Config > Replacement Message.
2. Click Create New or Clone the predefined message. Find the OAuth Login Page under Site Publish Authentication, then double click to edit it. Refer to Customizing error and authentication pages (replacement messages) for more information.
   Please note that the OAuth server defined in the OAuth Login Page should be the same with the OAuth Server Name in Application Delivery > Site Publish > OAuth Server Pool (see step 7 of Creating an OAuth Server pool).

   Picture 1: The value of the OAuth server defined in the OAuth Login Page
   

   Picture 2: the OAuth Server Name defined in Application Delivery > Site Publish > OAuth Server Pool