Fortinet black logo

Handbook

OAuth 2.0 authentication

OAuth 2.0 authentication

OAuth (Open Authorization) is an authorization framework that can provide client applications with a secure delegated access to server resources on behalf of a resource owner. OAuth works over HTTPS and authorizes third-party clients such as devices, APIs, servers, and applications with access tokens rather than credentials with the approval of the resource owner. The third party then uses the access tokens to access the protected resources hosted by the resource server. This enables applications to obtain limited access to HTTP services on behalf of a user by delegating the user authentication to the service that hosts the user account, and authorizing the third-party application to access the user account.

Through FortiADC's OAuth 2.0 feature, you can:

  • Mandate the authentication to a third party that you trust.

  • Enable your web application (RealServer) to access resources that belong to the user and do not belong to the web application (RealServer).

  • Implement an alternative to Single SignOn.

FortiADC will only be supporting OAuth 2.0 which is the most widely used form of OAuth. There will be no backwards compatibility between OAuth 1.0 and OAuth 2.0 as their specifications are so different that they cannot be used together.

Deploying OAuth 2.0 authentication

To deploy OAuth 2.0 in FortiADC, you need to first set up the OAuth policy to establish the authorization flow between FortiADC, the token server, and the authorization server. The OAuth policy serves to obtain the authorization code and access token. After the OAuth policy is set up, it is then applied in the authentication policy, in which you will apply to the virtual server to complete the OAuth deployment.

To configure the OAuth policy:
  1. Go to User Authentication > OAuth Proxy.
  2. Click +Create New.
  3. Configure the following settings:

    Settings

    Description

    Name Configuration name. Valid characters are A-Z, a-z, 0-9, _, and -. No spaces. After you initially save the configuration, you cannot edit the name.
    Client ID The client ID for your application.
    Client Secret The secret used to apply for the access token.
    Authentication URL The URL of the authorization server.
    Token URL The URL of the token server.
    Redirect URL The URL of the redirected server.
    Logout URL

    The URL will trigger a logout event in which the user will be logged out and FortiADC will delete the cookie. For the next access, the OAuth 2.0 process will need to be conducted again.

    The value is parsed as a match string prefix. For example, /abc matches http://www.example.com/abcd and http://www.example.com/abc/11.html but not http://www.example.com/1abcd.

    HTTP Method

    The HTTP method used for the OAuth transaction.

    Select from the following:

    • POST

    • GET

    Relay Mode

    Enable/disable relay mode allows FortiADC to add an Authorization Header to the HTTP request after verifying the token.

    Include Granted Scopes

    Select from the following:

    • True

    • False

    • None

    This enables applications to use incremental authorization to request access to additional scopes in context.

    If you set this parameter's value to True and the authorization request is granted, then the new access token will also cover any scopes to which the user previously granted the application access.

    Prompt

    Select from the following:

    • Disable — Disable prompts.

    • None — Do not display any authentication or consent screens.

    • Consent — Prompt the user for consent.

    • Select Account — Prompt the user to select an account.

    Token Timeout

    The amount of time in seconds the token will be valid. (Range: 120-86,400, default = 3600).

    The client will not be allowed to access the scope after this time has elapsed.

  4. Click Save.
To configure the authentication policy:
  1. Go to User Authentication > Authentication Policy.
  2. Click +Create New.
  3. Name the new authentication policy.
  4. Configure the following to set the Member as the OAuth for the new OAuth policy.
    1. Set the Type as OAuth.
    2. Specify the pathname.
    3. Select the applicable OAuth Policy.
  5. Click Save.
To apply the authentication policy to the virtual server:
  1. Go to Server Load Balance > Virtual Server.
  2. Click +Create New and select Advanced Mode. Or double-click an existing virtual server configuration from the list.
  3. In the General tab, under the Resources section, select the applicable Auth Policy.
  4. Click Save.

OAuth 2.0 scopes

Scopes enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. As part of the OAuth policy configuration, add the scopes to the Scope List to identify the resources your application could access on the user's behalf. These will be shown to the user to obtain their consent when they access the resource server. However, there is an inverse relationship between the number of scopes requested and the likelihood of obtaining user consent; the user must consent to all or none of the requests within the scope.

Note: OAuth 2.0 scopes are restricted to each application. Please refer to the applicable guidelines for your application to ensure the scopes are valid.

OAuth 2.0 authentication

OAuth (Open Authorization) is an authorization framework that can provide client applications with a secure delegated access to server resources on behalf of a resource owner. OAuth works over HTTPS and authorizes third-party clients such as devices, APIs, servers, and applications with access tokens rather than credentials with the approval of the resource owner. The third party then uses the access tokens to access the protected resources hosted by the resource server. This enables applications to obtain limited access to HTTP services on behalf of a user by delegating the user authentication to the service that hosts the user account, and authorizing the third-party application to access the user account.

Through FortiADC's OAuth 2.0 feature, you can:

  • Mandate the authentication to a third party that you trust.

  • Enable your web application (RealServer) to access resources that belong to the user and do not belong to the web application (RealServer).

  • Implement an alternative to Single SignOn.

FortiADC will only be supporting OAuth 2.0 which is the most widely used form of OAuth. There will be no backwards compatibility between OAuth 1.0 and OAuth 2.0 as their specifications are so different that they cannot be used together.

Deploying OAuth 2.0 authentication

To deploy OAuth 2.0 in FortiADC, you need to first set up the OAuth policy to establish the authorization flow between FortiADC, the token server, and the authorization server. The OAuth policy serves to obtain the authorization code and access token. After the OAuth policy is set up, it is then applied in the authentication policy, in which you will apply to the virtual server to complete the OAuth deployment.

To configure the OAuth policy:
  1. Go to User Authentication > OAuth Proxy.
  2. Click +Create New.
  3. Configure the following settings:

    Settings

    Description

    Name Configuration name. Valid characters are A-Z, a-z, 0-9, _, and -. No spaces. After you initially save the configuration, you cannot edit the name.
    Client ID The client ID for your application.
    Client Secret The secret used to apply for the access token.
    Authentication URL The URL of the authorization server.
    Token URL The URL of the token server.
    Redirect URL The URL of the redirected server.
    Logout URL

    The URL will trigger a logout event in which the user will be logged out and FortiADC will delete the cookie. For the next access, the OAuth 2.0 process will need to be conducted again.

    The value is parsed as a match string prefix. For example, /abc matches http://www.example.com/abcd and http://www.example.com/abc/11.html but not http://www.example.com/1abcd.

    HTTP Method

    The HTTP method used for the OAuth transaction.

    Select from the following:

    • POST

    • GET

    Relay Mode

    Enable/disable relay mode allows FortiADC to add an Authorization Header to the HTTP request after verifying the token.

    Include Granted Scopes

    Select from the following:

    • True

    • False

    • None

    This enables applications to use incremental authorization to request access to additional scopes in context.

    If you set this parameter's value to True and the authorization request is granted, then the new access token will also cover any scopes to which the user previously granted the application access.

    Prompt

    Select from the following:

    • Disable — Disable prompts.

    • None — Do not display any authentication or consent screens.

    • Consent — Prompt the user for consent.

    • Select Account — Prompt the user to select an account.

    Token Timeout

    The amount of time in seconds the token will be valid. (Range: 120-86,400, default = 3600).

    The client will not be allowed to access the scope after this time has elapsed.

  4. Click Save.
To configure the authentication policy:
  1. Go to User Authentication > Authentication Policy.
  2. Click +Create New.
  3. Name the new authentication policy.
  4. Configure the following to set the Member as the OAuth for the new OAuth policy.
    1. Set the Type as OAuth.
    2. Specify the pathname.
    3. Select the applicable OAuth Policy.
  5. Click Save.
To apply the authentication policy to the virtual server:
  1. Go to Server Load Balance > Virtual Server.
  2. Click +Create New and select Advanced Mode. Or double-click an existing virtual server configuration from the list.
  3. In the General tab, under the Resources section, select the applicable Auth Policy.
  4. Click Save.

OAuth 2.0 scopes

Scopes enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. As part of the OAuth policy configuration, add the scopes to the Scope List to identify the resources your application could access on the user's behalf. These will be shown to the user to obtain their consent when they access the resource server. However, there is an inverse relationship between the number of scopes requested and the likelihood of obtaining user consent; the user must consent to all or none of the requests within the scope.

Note: OAuth 2.0 scopes are restricted to each application. Please refer to the applicable guidelines for your application to ensure the scopes are valid.