OAuth Bearer Single Sign-On Method

OAuth Bearer SSO Method

Overview: Configuring SSO OAuth Bearer using passthrough

You can configure OAuth Bearer SSO as passthrough to use the JSON Web Token (JWT) received from the client. The OAuth scope check authenticates the client, and sends the received token to the backend server.

Before you start, you need to have created an access policy, access profile, and a virtual server to meet your needs. Here we configure OAuth Bearer SSO using the passthrough option for the token source.

Creating an OAuth bearer SSO configuration for passthrough

You create an OAuth bearer SSO configuration when you want to allow single-sign on using an OAuth token. In this task, the token is retrieved from the client, and is generated on an external OAuth authorization server.

1. On the Main tab, select Access > Single Sign-On > OAuth Bearer.

   The OAuth Bearer Configurations screen opens.

2. Click Create.

   The New SSO Configuration screen opens.

3. In the Name field, type a name for the SSO configuration.

   The maximum length of a single sign-on configuration is 225 characters, including the partition name.

4. For Send Token, select when to send the token:

   • To always send the token, select Always.
   • To send the token when you receive a 4xx response from the server, select On 4xx Response and choose one or more 4xx responses.

5. For Log Settings, select the log settings to use for the access event logs.

   By default, the log settings specified in the access profile are used. You can also create custom log settings or use the default-log-setting for this SSO configuration. Click + to create custom settings.

6. If getting the JWK token from the client, for Token Source, select Passthrough, and select a server from the OAuth Server list.

7. Click Finished.

When you configure an APM access policy that supports single sign-on, it includes an SSO Configuration property. Select the SSO bearer configuration from the object where you want to put SSO into effect.

For example, to use OAuth Bearer SSO, you need an access profile, access policy, and a virtual server. The access profile being used in this configuration must contain an OAuth Bearer SSO configuration. The virtual server needs to specify the access profile.

Example access policy configuration using passthrough

Here is an example access policy configured using passthrough. The JWT token received from the client is used, it goes through the OAuth scope check, and if the check is successful, the received JWT token is sent to the backend server.

Overview: Configuring SSO OAuth Bearer to create JWT

You can configure OAuth Bearer SSO to create, sign, and send a JSON Web Token (JWT) to backend applications that require an access token.

Setting this up requires performing the following tasks:

• Create claims for the JWT, as needed
• Create a JSON Web Key (JWK) configuration
• Create an OAuth Bearer SSO configuration
• Associate the OAuth Bearer configuration with the access profile
• Use AAA (AD query), SAML, or other authentication method in the access policy
• Assign the access profile to the virtual server

Before you start, you need to have created an access policy, access profile, and a virtual server to meet your needs. Here we add the OAuth Bearer SSO configuration to your environment.

About OAuth Bearer SSO

Bearer tokens are tokens that OAuth 2.0 uses to authorize clients to access protected resources.

OAuth Bearer SSO provides a JSON Web Token (JWT) in the form of a bearer token to the backend resource server. You can configure OAuth Bearer SSO as passthrough (where the JWT received from the client is used), or have APM generate and sign the JWT token for the backend SSO.

Configuring JWT claims

You can configure the claims that you want to include in the JSON Web Tokens (JWTs). (A claim specifies a string, and optionally, a value, that represents a resource.) This is only required if you plan to specify claims in your JWTs.

1. On the Main tab, select Access > Federation > OAuth Authorization Server > Claim.

2. Click Create.

3. In the Name field, type a name for the configuration.

4. From Claim Type, select the required claim type from the list. Available options are String, Number, Boolean, or Custom.

5. In the Claim Name field, type a name for the claim.

   Note: The following names are reserved claim names, and you cannot use them in OAuth claim configuration: iss, aud, sub, exp, nbf, iat, jti, x-jti, at_hash, c_hash, azp, acr, amr, sub-jwk, nonce, auth_time, _claim_names, _claim_sources, scope, scope_data, token_type, username, and id_token.

6. In the Claim Value field, type a value for the claim depending on its type.

7. Click Save.

   The newly created claim displays on the list.

You associate claims with tokens an OAuth bearer SSO configuration.

Configuring JSON web keys (JWKs)

A JSON web key configuration specifies a cryptographic JSON web key (JWK). You configure JWKs for the system to use to sign the JSON web tokens that it issues. For example, you use JWK key configurations when setting up OAuth bearer single sign-on.

1. On the Main tab, select Access > Federation > JSON Web Token > Key Configuration.

   The Key Configuration screen opens.

2. Click Create.

3. In the Name field, type a name.

4. In ID, type an ID.

   This parameter is used to identity a specific JSON web key.

5. For the JWT Type, it specifies the type of JSON Web Token (JWT). Click the applicable JWT type radio button. Available options are JWS and JWE. Select the JWS (JSON Web Signature) or JWE (JSON Web Encryption) option to generate corresponding token type.

6. For Type, select RSA, Octet, or Elliptic Curve. This option specifies the type of cryptographic algorithm used to sign the JSON web key.

   • RSA - Uses RSA algorithms
   • Elliptic Curve - Uses ECDSA algorithms
   • Octet - Uses HMAC algorithms Additional parameters display for the type that you select.

7. For Key Encryption Algorithm, select the required key. This option specifies the key encryption algorithm used in the JWE token generation. Available option is RSA-OAEP algorithm. Default option is None. This option appears when JWT Type is selected as JWE.

8. For Content Encryption Algorithm, select the required key. This option specifies the data encryption algorithm used in the JWE token generation. Supported options are A128GCM and A256GCM algorithms. Default option is None. This option appears when JWT Type is selected as JWE.

9. For Signing Algorithm, select the applicable options such as 256, 384, 512 from the list based on the Type selected. This option specifies RSA, ECDSA (Elliptic Curve), or HMAC (Octet) algorithms depending on the specific Type selected.

10. For the Octet type, you need to configure additional settings:

    1. For Use Client Secret, click the checkbox as needed. If selected, the client secret is used by the OAuth client to authenticate to the authorization server for an Octet type. In addition, the encoding format and shared secret are not needed. If not selected, the shared secret is used. When the check box is selected, this option hides the Encoding Format and Shared Secret options.

    2. For Encoding Format, select the required format. Available options are None and Base64url. Default selection is None.

    3. In Shared Secret, type the secret.

       Important: To maximize the security of the algorithm, use enough characters so that the resulting key size matches the block size for the signing algorithm: for HS256, 32 characters; for HS384, 48 characters; for HS512, 64 characters.

    4. Click Save.

       The newly created JWK displays on the list.

11. For the Octet type, you only need to configure one additional setting:

    1. In Shared Secret, type a secret.

       Important: To maximize the security of the algorithm, type enough characters so that the resulting key size matches the block size for the signing algorithm: for HS256, 32 characters; for HS384, 48 characters; for HS512, 64 characters.

    2. Click Save.

       The newly created JWK displays on the list.

12. To support an RSA or an Elliptic Curve key type, you must either configure settings in the Certificates area or in the Parameters area.

    To get the necessary parameters from a certificate, go to the Certificates area and configure these settings:

    1. In the Certificates area, for Certificate File, select a certificate.

       Important: When BIG-IP acts as an Authorization Server to generate the JWE token, select the Certificate file. If BIG-IP acts as a Client or Resource Server to consume the JWE token, select both Certificate file and corresponding Certificate Key.

       Important: When the BIG-IP system is on a chassis platform or is included in an HA pair, do not select the default certificate. F5 strongly discourages the use of the default certificate in a JWK in any configuration.

       Note: The Include X5C, Certificate Key, and Key Passphrase settings apply only for a JWK for use with APM as an OAuth authorization server.

    2. In the Certificates area, when the Include X5C checkbox is enabled, specifies that the JWKS endpoint response contains a chain of one or more PKIX certificates. This option appears when a certificate is selected from the Certificate File list.

    3. In the Certificates area, for the Certificate Key, select a certificate key from the list. This option specifies the certificate key that this JSON web key uses to sign the JWT.

       For a BIG-IP system on a chassis platform or in an HA pair, do not select the default certificate key, default.key. F5 strongly discourages the use of the default key in a JSON web key in any configuration.

    4. In the Certificates area, for the Key Passphrase, enter a key passphrase. This option specifies the passphrase used to encrypt the certificate key provided in the Certificate Key field.

    5. For Certificate Chain, select one.

    6. Click Save.

       The newly created JWK displays on the list.

13. For the RSA type, in the absence of a certificate, go to the Parameters area and complete these substeps:

    1. For Modulus, type the modulus of the RSA public key.

    2. For Public Exponent, type the public exponent of the RSA public key.

    3. Supply values for the SHA-1 Thumbprint, and SHA-256 Thumbprint fields.

    4. Click Save.

       The newly created JWK displays on the list.

14. For the Elliptic Curve type, in the absence of a certificate, go to the Parameters area and complete these substeps:

    1. For X Coordinate, type an X coordinate for the elliptic curve.

    2. For Y Coordinate, type an Y coordinate for the elliptic curve.

    3. For Curve, specify an elliptic curve.

       For example, type P-256.

    4. Supply values for the SHA-1 Thumbprint, and SHA-256 Thumbprint fields.

    5. Click Save.

       The newly created JWK displays on the list.

Creating an OAuth bearer SSO configuration to generate JWT

You create an OAuth bearer SSO configuration when you want to allow single-sign on using an OAuth token. SSO generates a signed JWT (JSON web token) and sends it to the backend as an OAuth bearer token.

1. On the Main tab, select Access > Single Sign-On > OAuth Bearer.

   The OAuth Bearer Configurations screen opens.

2. Click Create.

   The New SSO Configuration screen opens.

3. In the Name field, type a name for the SSO configuration.

   The maximum length of a single sign-on configuration is 225 characters, including the partition name.

4. For Send Token, select when to send the token:

   • To always send the token, select Always.
   • To send the token when you receive a 4xx response from the server, select On 4xx Response and choose one or more 4xx responses.

5. For Log Settings, select the log settings to use for the access event logs.

   By default, the log settings specified in the access profile are used. You can also create custom log settings or use the default-log-setting for this SSO configuration. Click + to create custom settings.

6. For Token Source, select Generate JWT and follow the remaining steps in this task to define the JWT.

7. For Issuer, type the URL for the JWT issuer. For example, https://jwt-issuer.com.

8. In Subject, retain the default value, %{session.assigned.uuid}, or type a subject for the JWT.

   The session variable session.assigned.uuid contains the UUID that the system assigns to the session after the access policy completes.

9. To increase performance until the cached JWT expires, click Enable Token Cache to store the token in cache for the session and reuse it as needed.

10. For Access Token Lifetime, type the number of minutes you want the JWT access token to be considered valid.

    The default is 5 minutes.

11. When the Ignore Expired Certificate Validation checkbox is selected, the certificate is used for signing a JWT access token even if it is expired. When cleared, the system sends an error message when the certificate has expired.

12. For the JWT Key Type, click the required JSON key type radio button. Specifies the type of JSON Web Token (JWT) key. Available options are JWS and JWE. This option is visible when the Generate JWT is selected from the Token Source dropdown. Select the JWS (JSON Web Signature) or JWE (JSON Web Encryption) option to generate corresponding token type. Based on the JWT key type selection (JWS or JWE), the respective JWT primary keys are populated and select the applicable keys from the dropdown list.

13. For the JWT Primary Key, select a JSON Web Key (JWK) configuration from the list. This option specifies the primary signing key for the JWT. This option is visible when the Generate JWT is selected from the Token Source dropdown. APM uses the JWK to retrieve the shared key (symmetric) or the private key (asymmetric) used to sign the JWT access token. If the key is asymmetric, the configured public key is returned as part of JWKS URL response.

    Note: JSON web keys are configured in the Access > Federation > JSON Web Token area of the product.

14. From Signing Key, select the JWK key configuration previously created for signing the token.

15. For Audience, add the audience claim or claims for which the JWT access token is intended. This is a list of values. Each value in this list can be a string, URI, or session variable.

16. For Scope, type one or more space-separated scope strings (using the ASCII character set) or session variables. For example, openid phone email.

    Note: For example, to create a JWT claim called scope, specify it here. You cannot use reserved words such as scope as the name of a JWT claim.

17. If you created claims for the token, for JWT Claims, move the previously created claims you want to use to the Selected list.

18. The other fields are not required but you can set them if needed.

19. Click Finished.

When you configure an APM object that supports single sign-on, it includes an SSO Configuration property. Select the SSO bearer configuration from the object where you want to put SSO into effect.

OAuth Bearer SSO configuration settings

These settings are available when you create an OAuth Bearer SSO configuration.

General Properties for OAuth Bearer SSO configuration

Passthrough OAuth Bearer SSO configuration settings

These are the settings to use when the bearer token is retrieved from another source.

Generate JWT OAuth Bearer SSO configuration settings

These are the settings to use when the system generates and signs the OAuth bearer token. For this configuration, you need to have created a JWK key configuration and optional JWT claims.

Adding OAuth bearer SSO to an access profile

You add an OAuth bearer SSO configuration to an access profile if you want to allow single sign-on using an OAuth bearer token.

Note: You can also select an SSO configuration from a portal access resource.

1. On the Main tab, click Access > Profiles / Policies > Access Profiles (Per-Session Policies).

   The Access Profiles (Per-Session Policies) screen displays.

2. Click the name of the access profile that you want to edit.

   The properties screen opens.

3. Click SSO / Auth Domains on the menu bar.

   The SSO Across Authentication Domains screen opens.

4. From the SSO Configuration list, select the OAuth bearer SSO configuration you want the access profile to use.

   Other settings on the screen are not relevant when using an OAuth bearer SSO configuration.

5. Click Update.

An access profile goes into effect when it is associated with a virtual server.

Example access policy configurations generating JWTs

Here is an example access policy using an OAuth scope check. If the check is successful, an AD Query retrieves more user data. Then, SSO generates the JWT access token with the retrieved infromation and sends it to the backend server.

Here is an example access policy configured with an AAA agent. It goes through the OAuth scope check. If the check is successful, an AD Query retrieves more user data. Then, SSO generates the JWT token with the retrieved infromation and send to the backend server.

Here is an access policy configured with a SAML SP agent. SAML authentication retrieves the SAML2.0 bearer token and validates.

Adding the access profile to the virtual server

You associate the access profile with the virtual server so that the system can apply the profile to incoming traffic.

1. On the Main tab, click Local Traffic > Virtual Servers.

   The Virtual Server List screen opens.

2. Click the name of the virtual server you want to modify.

3. In the Access Policy area, from the Access Profile list, select the access profile that you configured earlier.

4. Click Update to save the changes.