Trading Networks 10.3 | Administering and Monitoring B2B Transactions | Integration Server Administrator's Guide | Configuring OAuth | Configuring Integration Server for OAuth | Defining Clients | Registering Clients
 
Registering Clients
Clients must be registered with the Integration Server acting as the authorization server to be able to access resources protected by OAuth.When you register a client, you identify the client as a confidential client or a public client, select the grant types the client can use, and specify token expiration and refresh information.
For each OAuth client registered with Integration Server, you must specify the OAuth grant types that the client can use to access the server. Keep the following information in mind when selecting the grant types that a client can use.
*Only confidential clients may use the client credentials grant and resource owner password credentials grants. You cannot select either of these grant types for public clients. If a client requests an access token using a grant that it is not allowed to use, Integration Server will reject the request and return an unauthorized_client OAuth error.
*When you register a new client, Integration Server automatically selects the Authorization Code Grant check box.
*The authorization code grant is the most secure of the four OAuth grant types. supported by Integration Server.
*If you select the Authorization Code Grant or the Implicit Grant check boxes, you need to enter at least one Redirection URI for the client.
*After registering a client that will use the client credentials grant, you must give the client permission to access the resources it needs. This is different than the other grants. For the other grants, Integration Server knows the owner because the resource owner is involved in the grant flow. Specifically, when an access token is being used to access a resource, Integration Server checks that the owner has permission to access the resource. With the client credentials grant, Integration Server does not know the owner. Consequently, it is the client who must have permission to access the resources. After registering the client, you must add the client to one or more user groups that belong to the access control lists (ACLs) that the client needs. The client ID generated for the client by Integration Server appears as the user name on the Security > User Management screens.
Note:
Prior to Integration Server version 10.3, registering a client did not require specifying allowed grant types. Rather, all registered clients were allowed to use the authorization code grant type and the implicit grant type. Beginning in Integration Server 10.3, all new clients must specify at least one grant type. Clients migrated to Integration Server 10.3 will still be able to use the authorization code grant type and the implicit grant types.
Complete the following steps to register a client with the authorization server.
*To register a client
1. Open Integration Server Administrator of the Integration Server defined as the authorization server if it is not already open.
2. In the Security menu of the Navigational Panel, click OAuth.
3. Click Client Registration.
4. Click Register Client.
5. Under Client Configuration, complete the fields as follows:
Field
Description
Name
Specifies the name of the client.
The name cannot contain the following characters:
& ( ) \ ; , / " : ' < >
Note:
You cannot create clients with the same Name and Version combination.
Version
Specifies the version number of the client.
The version cannot contain the following characters:
& ( ) \ ; , / " : ' < >
Note:
You cannot create clients with the same Name and Version combination.
Type
Specifies the type of the client according to its ability to communicate with the authorization server.
Specify...
When...
Confidential
The client is capable of maintaining secure client authentications. When you select client type as Confidential, Integration Server generates a client secret. This client secret will be required by Integration Server when the client makes requests to the OAuth services. Specify Confidential when the OAuth session uses the authorization code grant type, resource owner password credentials grant type, or the client credentials grant type.
Public
The client is not capable of maintaining secure client authentications. Specify Public when the OAuth session uses the implicit grant type. For more information, see Implicit Grant.
Description
Optional. Specifies a description of the client.
Redirect URIs
Specifies the URIs that the authorization server will use to redirect the resource owner's browser during the grant process.
You can add more than one URI at a time by specifying multiple lines, one URI to a line. Press the Enter key to separate lines.
If you select the Authorization Code Grant or the Implicit Grant types, you need to enter at least one Redirection URI for the client.
Allowed Grants
Specifies the OAuth grant types that the client can use to with Integration Server. Select one or more of the following:
*Authorization Code Grant
*Implicit Grant
*Client Credentials Grant
*Resource Owner Password Credentials Grant
The default is Authorization Code Grant which is the most secure grant type.
If you select Authorization Code Grant or Implicit Grant, you need to enter at least one redirect URI for the client.
Only confidential clients may use the client credentials and resource owner password credentials grants. You cannot select either of these grants for public clients. If a client requests an access token using a grant that it is not allowed to use, Integration Server will reject the request and return an unauthorized_client OAuth error.
6. Under Token, specify the following information about the tokens issue to the client:
Field
Description
Expiration Interval
Specifies the length of time (in seconds) that the access token is valid.
Select...
To...
Use OAuth Global Setting
Use the setting specified in the Access token expiration interval field on the OAuth screen. This setting is shown in angle brackets. For more information about the Access token expiration interval field, see Configuring OAuth Settings.
Never Expires
Indicate that the access token never expires.
Expires in
Specify a specific time interval. Enter the number of seconds that the access token is valid in the field provided. The maximum value is 2147483647. The default is 3600.
Refresh Count
Specifies the number of times the access token can be refreshed.
Note:
Tokens can only be refreshed when using the authorization code grant flow and the resource owner password credentials (ROPC) grant flow.
Select...
To...
Unlimited
Refresh the access token an unlimited number of times.
Limit
Specify the number of times Integration Server can refresh the access token.
If you specify any value greater than 0, Integration Server will issue a refresh token to enable the access token to be refreshed the specified number of times. When the access token expires, the client can use the pub.oauth:getToken service to submit a token refresh request to the authorization server.
If you specify 0 or leave the Limit field empty, Integration Server does not issue a refresh token.
The maximum value is 2147483647. The default is 0.
7. Click Save Changes.
Integration Server generates a client ID. If you specified Confidential in the Type field, Integration Server also generates a client secret. Integration Server requires the client ID, client secret, or both when the client invokes the OAuth services.
Note:
When a confidential client is registered, a corresponding Integration Server user account is created. The user name is the client ID and the password is the client secret. If an existing client is changed from confidential to public or vice versa, the corresponding user account is created or deleted.
Note:
The password automatically generated for the Integration Server user account might not conform to password restrictions. However passwords that Integration Server generates automatically for OAuth clients are secure 36 character pseudo-random values.