Manual Chapter :
OAuth Bearer Single
Sign-On Method
Applies To:
Show VersionsBIG-IP APM
- 15.1.10, 15.1.9, 15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0
OAuth Bearer Single
Sign-On 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.
- On the Main tab, select.The OAuth Bearer Configurations screen opens.
- ClickCreate.The New SSO Configuration screen opens.
- In theNamefield, type a name for the SSO configuration.The maximum length of a single sign-on configuration is 225 characters, including the partition name.
- ForSend Token, select when to send the token:
- To always send the token, selectAlways.
- To send the token when you receive a 4xx response from the server, selectOn 4xx Responseand choose one or more 4xx responses.
- ForLog 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 thedefault-log-settingfor this SSO configuration. Click+to create custom settings.
- If getting the JWK token from the client, forToken Source, selectPassthrough, and select a server from theOAuth Serverlist.
- ClickFinished.
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.- On the Main tab, select.
- ClickCreate.
- In theNamefield, type a name for the configuration.
- FromClaim Type, select the required claim type from the list. Available options areString,Number,Boolean, orCustom.
- In theClaim Namefield, type a name for the claim.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, andid_token.
- In theClaim Valuefield, type a value for the claim depending on its type.Claim TypeValue can beStringEnter ASCII characters or session variable in the Claim Value field. Do not encapsulate the provided claim value in the escaped quotes (\").NumberEnter a valid number or a session variable in the Claim Value field.BooleanEntertrue,false, or a session variable in the Claim Value field.CustomSelect this option when the claim value is a JSON value type array, object, or null in the Claim Value field.When the Claim Type is set to Custom, you can use both Object (array, null) or String (claim type String is recommended) in the claim value. Ensure the string value is encapsulated in the escaped quotes (\"). For example, if an array contains strings, number, boolean, and null, encapsulate only the string values in quotes within the array. Claim Value = [\"example\", \"Strings\", 5, true, null].
- ClickSave.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.
- On the Main tab, select.The Key Configuration screen opens.
- ClickCreate.
- In theNamefield, type a name.
- InID, type the ID.
- ForType, selectRSA,Octet, orElliptic Curve.Additional parameters display for the type that you select.
- ForSigning Algorithm, select any one.
- For theOctettype, you only need to configure one additional setting:
- InShared Secret, type the secret.To maximize the security of the algorithm, use enough characters so that the resulting key size matches the block size for the signing algorithm: forHS256, 32 characters; forHS384, 48 characters; forHS512, 64 characters.
- ClickSave.The newly created JWK displays on the list.
- For theRSAorElliptic Curvekey types, configure the settings in the Certificates areas:
- ForCertificate File, select a certificate.Do not select the default certificate when the BIG-IP system is on a chassis platform or is included in an HA pair. F5 strongly discourages the use of the default certificate in a JWK in any configuration.
- ForCertificate Key, select one.Do not use the default key when the BIG-IP system is on a chassis platform or is included in an HA pair. F5 strongly discourages the use of the default key in a JWK in any configuration.
- ForKey Passphrase, type a passphrase.
- ForCertificate Chain, select one.If this field is filled in, values for the parameters are auto-generated.
- ClickSave.The newly created JWK configuration displays in 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.
- On the Main tab, select.The OAuth Bearer Configurations screen opens.
- ClickCreate.The New SSO Configuration screen opens.
- In theNamefield, type a name for the SSO configuration.The maximum length of a single sign-on configuration is 225 characters, including the partition name.
- ForSend Token, select when to send the token:
- To always send the token, selectAlways.
- To send the token when you receive a 4xx response from the server, selectOn 4xx Responseand choose one or more 4xx responses.
- ForLog 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 thedefault-log-settingfor this SSO configuration. Click+to create custom settings.
- ForToken Source, selectGenerate JWTand follow the remaining steps in this task to define the JWT.
- ForIssuer, type the URL for the JWT issuer. For example,https://jwt-issuer.com.
- InSubject, retain the default value,%{session.assigned.uuid}, or type a subject for the JWT.The session variablesession.assigned.uuidcontains the UUID that the system assigns to the session after the access policy completes.
- To increase performance until the cached JWT expires, clickEnable Token Cacheto store the token in cache for the session and reuse it as needed.
- ForAccess Token Lifetime, type the number of minutes you want the JWT access token to be considered valid.The default is 5 minutes.
- FromSigning Key, select the JWK key configuration previously created for signing the token.
- ForAudience, 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.
- ForScope, type one or more space-separated scope strings (using the ASCII character set) or session variables. For example,openid phone email.For example, to create a JWT claim calledscope, specify it here. You cannot use reserved words such asscopeas the name of a JWT claim.
- If you created claims for the token, forJWT Claims, move the previously created claims you want to use to theSelectedlist.
- The other fields are not required but you can set them if needed.
- ClickFinished.
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
Setting | Value | Additional
Information |
---|---|---|
Name
| Name of the SSO configuration. | The name must begin with a letter, or
underscore, and contain only letters, numbers, underscores, dashes, and periods. Maximum length
including the partition name is 225 characters. Avoid using global reserved words in the name,
such as all, delete, disable, enable, help, list, none, show, or None. |
SSO Method
| Displays the type of SSO
configuration. | Cannot be changed. |
Headers
| Header name-value pairs to send with
the SSO method. | Available when you select Advanced from the General Properties list. |
Send Token
| Specifies when to send the token
(for OAuth Bearer). | Specify Always
to always send the token.Specify On 4xx
Response to send the token when you receive a 4xx response from the server;
select On 400 , On 401 , and/or On 403 . The system first forwards the user's
HTTP request to the web server without inserting the token. If the server requests
authentication by responding with a 4xx status code (that is enabled), the system retries the
request with the token. |
Log Settings
| Specifies which log settings to use
for the access event logs. By default, the log settings specified in the access profile are
used. | You can create custom log settings or
use the default-log-settings for this SSO configuration. Click + to create custom
settings. |
Passthrough OAuth Bearer SSO configuration settings
These are the settings to use when the bearer token is retrieved from another source.
Setting | Value | Additional
Information |
---|---|---|
Token Source
| Specifies
Passthrough to indicate that the user has a token from another
source. | Default value |
OAuth Server
| Specifies the OAuth server that
provided the token. | Required value |
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.
Setting | Value | Additional
Information |
---|---|---|
Token Source
| Specifies Generate JWT to indicate that you want the
system to create a JWT access token. | The system creates a JWT token and
sends it to the backend server as an OAuthBearer token. |
Issuer
| Specifies the issuer of the JWT. | This must be a URI and it is
mandatory. For example, https://authserver/oauth2 . |
Subject
| Specifies what the token is intended
for. | The value can be a string, URI, or
session variable, such as %{session.assigned.uuid} . |
Enable Token Cache
| When selected, stores the token in
cache for the session and reuses it; enabling the cache provides increased performance. | When cleared, the token is generated
for every request. |
Access Token Lifetime
| Specifies the number of minutes a
JWT access token is considered valid. | The default is 5 minutes. |
Ignore Expired Certificate
Validation
| When selected, the certificate is
used for signing a JWT access token even if it is expired. | When cleared, the system sends an
error message if the certificate has expired. |
Signing
Key
| Specifies a JSON web key (JWK)
configuration for signing the token. | It is mandatory. You can create JWKs
in
. |
Audience
| Specifies the audience claim 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. For example, https://newapp . |
Scope
| Specifies one or more
space-separated scope strings (using the ASCII character set) or session variables. | For example, openid phone
email . |
JWT Claims
| Specifies a list of claims that
define additional information that you want to transmit as part of the JWT access token. | You can create claims in
. |
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.
You can also select an SSO configuration from a
portal access resource.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- Click the name of the access profile that you want to edit.The properties screen opens.
- ClickSSO / Auth Domainson the menu bar.The SSO Across Authentication Domains screen opens.
- From theSSO Configurationlist, 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.
- ClickUpdate.
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.
- On the Main tab, click.The Virtual Server List screen opens.
- Click the name of the virtual server you want to modify.
- In the Access Policy area, from theAccess Profilelist, select the access profile that you configured earlier.
- ClickUpdateto save the changes.