Configuring an identity agent for authentication by using a web service

About this task

A nonstandard identity provider configuration that retrieves user attributes and groups from a web service accessing a nonstandard data source (non-ldap or non-ad).

Procedure

  1. Select Integrations > Identity agents.
  2. Select Create agent configuration.
  3. Select Authentication as the purpose.
  4. Select the Web service tile.
  5. Select Next.
  6. Configure the web service connection settings. Enter the on-premises web service URI.
    For a cluster web service failover setup, multiple web service URIs can be added by selecting ADD URI+.
  7. Select the authentication type.
    The authentication type is the method that the agent uses to authenticate itself with the on-premises web service.
    • OAUTH
      Token Endpoint URL
      Enter the token endpoint of the OAuth provider. This token endpoint is used by the agent to retrieve an access token that is sent to the web service.
      Token Endpoint Authentication Method
      Enter the token endpoint authentication method:
      • Client secret post - Agent sends client credentials to the token endpoint in a POST request.
      • Client secret basic - Agent sends the base64 encoded client credentials to the token endpoint in an authorization request header.
      Client ID and Client Secret
      Enter the client credentials used for authentication with the OAuth provider. You can also provide a certificate authority.
      If you are editing an existing Identity Agent client, you can use the following client secret options:
      • Select Show to view the client secret.
      • Select Hide to hide the client secret.
      • Select Copy to copy the client ID or secret to the clipboard.
      • Select List to view rotated client secrets.
        • Select one or more rotated client secrets from the list, and click Delete to delete them.
      • Select Regenerate to generate a new client secret. Use this option if you think that the client secret is compromised. If you do regenerate the client secret, you must update the client secret in all the OAuth clients for the application.
        • Select the checkbox for Retain current secret to add the current client secret to the list of rotated client secrets.
        • If the Retain current secret checkbox is selected, choose the client secret description and expiration time (in browser local time). If no expiration time is selected, the tenant's Rotated secret lifetime set in the Application settings will apply.
        • Rotated client secrets are hashed and cannot be retrieved in plain text anymore, but they can still be used until the selected expiration date.
        • After confirmation, the client secret is immediately rotated. The new client secret is shown on the screen.
      Private key certificate authority (optional)
      Enter the CA certificate chain to enable the on-prem agent to validate the external authentication service Transport Layer Security (TLS) connection.
      Scope entitlements (optional)
      Enter one or more scope entitlements for the access token.
      Private key certificate name (optional)
      If you want to perform Mutual TLS (MTLS) certification authentication with your agent connection, provide the private key certificate name.
    • JSON Web Token (JWT)
      HTTP Header
      Enter the HTTP header that the JWT appears in. For example, authorization.
      JWT header value prefix (optional)
      Enter the prefix value that appears before the JWT in the HTTP header. For example, Bearer .
      Note: A space is not automatically inserted between the prefix and the JWT and therefore must manually be entered following the specified prefix.
      Sub claim
      Enter the sub claim that appears in the JWT.
      Signing algorithm
      Select the signing algorithm that the agent uses to sign the JWT.

      For symmetric signing algorithms (HSXXX), enter the Secret Key value that is symmetric signing key. The signing key that is entered must be base64 encoded.

      For asymmetric signing algorithms (ESXXX, PSXXX, or RSXXX), enter the personal certificate name that is label of the private key that is used to sign the JWT. On Window systems, this label corresponds to the Subject value of the private key certificate within the windows keystore. On Linux® systems, this value corresponds to the label portion of the path /cert/{label}_cert[_{instance}].pem.

      Maximum valid lifetime or the JWT
      Enter the time value in seconds that the JWT is valid.
      Certificate authority (optional)
      Enter the CA certificate chain to enable the on-prem agent to validate the external authentication service TLS connection.
    • Basic Authentication
      Username and password
      The username and password that are used to authenticate the agent with the web service. They are sent to the web service in a header that is called authorization in the format Basic username:password where username:password is base64 encoded.
      The certificate authority (optional)
      Enter the CA certificate chain to enable the on-prem agent to validate the external authentication service TLS connection.
      Private key certificate name (optional)
      If you want to perform MTLS certification authentication with your agent connection, provide the private key certificate name.
    • Certificate authentication (MTLS)
      The certificate authority (optional)
      Enter the CA certificate chain. This certificate chain is used by the on-premises agent to validate the TLS certificate that is presented by a web service that uses TLS. This certificate chain is also be used by the agent when it validates the TLS certificate that is presented by the OAuth server's token endpoint URL.
      Private key certificate
      Enter the name of the private key certificate that the agent uses during MTLS. For authentication types other than MTLS, setting this value causes the agent to attempt to perform MTLS in addition to the already specified authentication type.

      On Windows systems, the bridge looks at the Subject: value in the Windows keystore. On Linux systems, the bridge looks at the path /cert/{label}_cert[_{instance}].pem where label is the value that is entered here.

  8. Click Next.
  9. Set the user properties.
    Provide a list attributes separated by commas that the web service returns for a successful password verify operation.
  10. Click Next.
  11. Map the attributes that are retrieved by the web service to the Verify Cloud Directory attributes.
    After you create the identity agent, you can change or update the mappings by using the edit function pencil icon on the agent's tile.
  12. Select Next.
  13. In Finalize configuration, provide the following information.
    • A unique and recognizable name for the agent
    • A description
    • A display name for the identity provider
    • A realm for the identity provider
  14. Optional: Select View advanced settings to add configuration attributes or to select a certificate for encryption.
  15. Click Save and continue.
  16. In Next steps , do the following steps.
    1. Select View API credentials and use the copy to clipboard icon to copy and store the Client ID and Client secret.
      Note: Only users with the proper entitlements can see the client secret. For more information, see Security updates for entitlements.
    2. If not already downloaded, download the agent from IBM® X-Force® App Exchange.
    3. Add your API credentials to the agent configuration.
  17. Click Finish.
    The configuration is added to Identity agents and the identity provider is listed in Authentication > Identity providers.