Registering Clients with the OAuth Manager

The OAuth Manager displays information about registered OAuth clients and associated OAuth tokens that are used to access OAuth protected resources.
otk43
The OAuth Manager displays information about registered OAuth clients and associated OAuth tokens that are used to access OAuth protected resources.
  oauthManager.png  
Perform the following tasks that are related to the OAuth Manager:
Log into the OAuth Manager
To log into OAuth Manager:
  1. Open a browser and go to:  https://<yourgatewayURL>:8443/<instanceModifier>/oauth/manager
  2. Provide a username and password. The type of access you are granted depends on your user role. See  OTK User Role Configuration.
  3. Click 
    Clients
     to list, delete, and register OAuth clients.
Register a Client
To register a client:
  1. Open the OAuth Manager.
  2. Click 
    Clients
    .
  3. Click 
    Register a New Client
    .
    registerNewClient.png  
  4. Fill out the form using the fields below, then click 
    Register
    Field
    Field Option
    Note
    Client Name
    Required. Do not use leading, trailing, or multiple spaces.
    Organization
    Required. Do not use leading, trailing, or multiple spaces.
    Description
    Optional
    Registered By
    Set to your logged in username. 
    Client Type
    confidential
    Default. More secure.
    public
    Less secure.
    Client Key
    System generated UUID. You can overwrite it.
    Authentication Method
    Client Secret (Basic)
    Client authenticates with authorization server by including the Client ID and Client Secret as client credentials using the HTTP Basic authentication scheme. This option is default.
    Client Secret (Post)
    Client authenticates with authorization server. It includes the Client ID and Client Secret as client credentials in the body of the request.
    Client Secret (JWT)
    Client authenticates with authorization server using JWT signed with client secret.
    Private Key (JWT)
    Client authenticates with authorization server using a JWT signed with a private key. Using this option, either jwks or jwks_uri must be defined to share the public key with the Authorization server. See  Client Authentication for more details.
    jwks
    The value of client JSON Web Key Set
    jwks_uri
    The URL of the client JSON Web Key Set. Example: https://[Gateway]:[port]/[file].json
    Client Secret
    System generated UUID. Maximum 255 characters.
    Master Key
    Applies only to clients using the CA Mobile API Gateway (MAG). Check the box to make the client key a master key. This enables dynamic client id creation. See MasterKey.
    Status
    ENABLED
    Allows the client app to be used immediately after registration. 
    DISABLED
    Suspends use of the client app.
    Scope
    Provide the default scope requests for the client. Maximum 4000 characters.
    For details, see Scope.
    Callback URL
    Provide values. For details, see Callback.
    Environment
    The 
    Environment 
    value is not validated by the OTK by default. Set the value to the client's associated platform such as iOS, Android, or web. You can enter the environment value to filter search results from the List Keys page. You can also customize OTK policies to take advantage of environment information during OAuth related requests.
You have registered a new client. 
Set the Master Key for Mobile Clients
The 
Master Key
 setting applies only to mobile clients using the CA Mobile API Gateway (MAG) and enables dynamic client id creation. 
If you are using MAG registered mobile clients, you must click Master Key to enable dynamic client id creation. Static client id creation is deprecated.
A master key allows the registered MAG client to retrieve new client credentials at the 
/connect/client/initialize
 default endpoint but not to consume any protected endpoints. The endpoint issues an original set of client credentials for an initial application registration, then upgrades client credentials for a known client_id. This dynamic client id creation allows for multiple instances of the same running app and is used for device-to-device login.
  masterKeyCheckbox.png  
Click the check box to indicate that client key for this client is a master key. The option to specify a client secret is unavailable. When the key is added, the OAuth Manager automatically sets the client secret value to the client_id value. Similarly, if you manually set the client secret to the generated client key, the client is treated as having a master key.
Behavior is as follows:
  • Only master keys can be used to access the /connect/client/initialize API which initializes the Mobile SDK with the MAG server. The API endpoint dynamically issues unique client credentials (non-master keys). 
  • Only clients with non-master keys can request OAuth tokens.  
  • If a master key is deleted, all keys that were issued based on that master key are also deleted. Any mobile app that is configured with a deleted key is disabled.
  • For the first app on a non-registered device, a new set of client credentials is registered with the device-id.  
  • For subsequent apps, a new set of client credentials is registered with the username that is associated with the given device-identifier. Earlier client credentials that are associated with a device-id are updated to the username. 
Set the Callback URL
The callback_uri is also known as the redirect_uri in OAuth 2.0.
For OAuth 2.0, the redirect_uri parameter may be used with response types.
The value of the callback_uri is a comma separated list of absolute URLs. You must include the scheme.
Valid callback_uri
Invalid callback_uri
https://example.ca.com/callback,https://another-callback.ca.com/granted
example.ca.com
https://example.ca.com:9876/callback?key=value
myscheme://for.my.mobile.native.app
Set Scope
The scope is a space-separated list of values that apply to OAuth 2.0 clients only and limit access for OAuth tokens. A client is initially registered with a set of scope values. These become the default scope requests for the client. For mobile clients, the default scope values are imported to the Mobile SDK through the msso_config.json file.
To restrict a scope request to a 
subset
 of the default set, set the scope request explicitly on the client side. A client cannot be granted a scope that does not belong to the registered default set. If the requested scope contains explicit scope requests that are outside of the registered default set, the access token is removed and a new access request is required using scopes within the default set.
To add a scope that is not in the default set, you must re-register the client with a new default set containing the new scope, and must export the msso_config.json file to the SDK. 
An OAuth protected API can require specific scope values. Any access_token used at that API must be granted for all required scope values, otherwise the request fails.  If no scope is registered and no scope is requested, scope is set to 'oob'.
Default supported scope values are as follows:
Open ID Connect Scope Values
Scope Value
Notes
openid
The OpenID Connect scope enables clients to send requests to the /userinfo endpoint. This scope causes the server to issue an id_token.
 
address
Requires openid scope.
phone
Requires openid scope.
email
Requires openid scope.
profile
Requires openid scope.
user_role
Requires openid scope.
 Returns the role of the resource_owner. By default it is 
user
 or 
admin
. The role 
admin
 is used in the OAuth Manager and MAG Manager to identify an administrator. It has to be requested with 'openid'. This Scope value is an OTK extension; it is not part of OpenID Connect.
Mobile Single Sign-On Related Scope Values
The scope request determines the authorization that is granted to the client by the resource owner.  If the requested scopes match or are a subset of the registered scope, access to the protected resource is granted. For mobile clients, the default scopes are imported to the Mobile SDK through the msso_config.json file.
Requires a Mobile API Gateway (MAG) installation.
Scope Value
Authentication Flow
Notes
msso
User Credentials
The username/password scope. Used for device registration with user credentials. Password grant type request.
Requires openid scope. Clients requesting an access_token using the msso scope also receive an id_token that enables mobile single-sign on across multiple apps.
Default endpoint for the user credentials workflow is /connect/device/register.
msso_register
User Credentials
The social login scope. Same as the msso scope, but is required for mobile single sign-on when using social login credentials. Follows the user credentials workflow for the password grant type.
Default endpoint for the user credentials workflow is /connect/device/register
msso_client_register
Client Credentials
The device to device scope. Required for mobile single sign-on with client credentials, not user credentials. Clients must be of type "confidential" to use the client credentials workflow.  By default, clients using this scope can register a device. The client id and client secret are used for device registration.
Default endpoint for the client credentials endpoint is /connect/device/register/client. This default endpoint is set in the MAG Variable Configuration assertion as the device_register_client_endpoint_path.
Mobile App Services Scope Values
Requires a Mobile App Services installation.
MAS Service
Related Scopes
Notes
MAS Storage
mas_storage
Required to access MAS Storage functionality.. Used to Manage user and group access to messages from enterprise identity providers.
MAS Messaging
mas_messaging
Required to access MAS Messaging functionality. Supports messaging using the MQTT Pub/Sub model. 
MAS Identity
mas_identity_retrieve_<resource>
mas_identity_create_<resource>
mas_identity_update_<resource>
mas_identity_delete_<resource>
Used for clients to store user messages locally on the device or in the cloud.
At least one of the scopes is required.
Scopes permit the app to retrieve, create, update, and delete data for a resource.
For example, mas_identity_retrieve_users allows the app to retrieve users.
The specified <resource> value is one of the following SCIM resource types:
  • users
  • groups 
The following additional SCIM resource types are accessible by default when any of the valid mas_identity* scopes are requested:
  • ServiceProviderConfig
  • ResourceTypes 
  • Schemas 
Manage Clients
In the OTK, to request OAuth tokens and consume OAuth protected APIs, clients must be registered. The Manage Clients page allows you to add, edit, or delete clients.
  manageClients.png  
 
Client management is not available via the OAuth Manager if the CA OAuth Toolkit has been integrated with the CA API Portal.
Available Actions 
  actionClientsOauthMan.png  
The available actions are:
  •  
    Delete
     – If you delete the client application, all client IDs that are issued for the client are also deleted.
  •  
    Edit 
    – Edit the client name, organization, description, and client type.
    Also allows you to set a value in JSON format for the client_custom field.
    Click 
    Update Client
     to save any changes.
  •  
    List Keys
     – Displays individual client information.
    The following table shows additional information for selected fields.
List Client Keys
All registered client_keys for the given client application appear on the list client keys page.  
Click 
Add Client Key
 to create additional keys for this client.  
Available Actions
  listkeyActions.png  
Perform any of the following available actions for a specific client key:
  •  
    Revoke
     –  Deletes the client key. All tokens for this client key are also revoked.
  •  
    Edit 
    – Edit properties for the key such as changing the status, disabling the key, adding scopes, and providing a Callback URL.
    Disabling a client key prevents the client key from being used for any future tokens, however it does not disable the tokens for that client key.
    Allows you to set a value in JSON format for the client_key_custom field.
    Allows you to set the Service IDs and Account Plan Mapping IDs values that are used in the CA API Portal.     
  •  
    Disable Tokens
     – Disables all tokens for the client key.
  •  
    Export
     –  Used to export client information in JSON message format. Accesses the current server configuration values. Use the JSON message to initialize OAuth clients or the CA Mobile API Gateway SDK for mobile applications.    
Field Information  
 
Field 
 
 
Notes
 
 
client_ident
 
The identifier of the client.
 
client_key
 
In OAuth 2.0 the 
client_key = the client_id
. They are synonymous terms.Maximum 255 characters.
 
secret
 
The client secret. If the client key and the secret are the same value, the client key is used as the master key in other endpoints/policies.Maximum 255 characters. 
 
scope
 
The allowed scopes for the client.
Maximum 4000 characters.
 
environment
 
Identifies the client platform.
 
callback
 
In OAuth 2.0, call back is the redirect_uri. Multiple URIs are supported.
 
expiration
 
The date until this key is valid. A value of 0 indicates that the key never expires.
 
status
 
Either "ENABLED" or "DISABLED". Disabled tokens cause resource requests to be denied.
 
client_key_custom
 
A custom field that is associated with the client key.
The custom value must be a valid JSON object and cannot contain the following characters: < > &
 
serviceIds
 
A comma separated list of key strings that identify API services that are registered with the CA API Portal.
 
accountPlanMappingId
 
A comma separated list of key strings that identify account plans registered with the CA API Portal.
Manage Tokens
To manage tokens using the OAuth Manager:
  1. Open a browser and navigate to this URL:
    https://<Gateway_host>:8443/oauth/manager
    The home page of the OAuth Manager appears.
  2. Click 
    Tokens
     to view values of issued tokens, and to disable or revoke tokens.
    The following table shows additional information for selected fields.
     
    Field
     
     
    Description
     
     
    rtoken
     
    refresh_token
     if available
     
    rexpiration
     
    The expiration date of the refresh token
     
    client_key
     
    In OAuth 2.0 it is the "client_id"
     
    status
     
    Disabled tokens cause resource requests to be denied
Available Actions
  tokenActions.png  
Perform any of the following available actions for a specific token:
  •  
    Revoke 
    –  Deletes the token.
  •  
    Disable/Enable
     – Toggles the current state of the token between invalid and valid.