Creating an OAuth2 Client

You can create OAuth2 clients with specific permissions for your application to work with Predix Platform services. Often this is the first step after creating an instance of a service.

About this task

When you create an instance of UAA, the UAA Dashboard is available for configuring that instance of UAA. You can use the Client Management tab in the UAA Dashboard to create the OAuth2 clients.

If you are prefer using the UAA command-line interface (UAAC) instead of UAA Dashboard to create an OAuth2 client, see t_using_uaac_to_create_an_oauth2_client.html#task_sp2_zvk_rdb

Procedure

  1. In the Predix.io Console view, select the Space where your services are located.
  2. In the Services Instances page, select the UAA instance to configure.
  3. Select the Configure Service Instance option.
  4. In the UAA Dashboard login page, specify your admin client secret and click Login.
  5. In UAA Dashboard, select the Client Management tab.
    The Client Management tab has two views, Clients and Services . The Services view displays the service instances that you have created for your services.
    Note: The service instances displayed in the Services view were created while using the UAA that you are trying to configure. Service instances that you created using other UAA instances are not displayed on this page.
  6. Click Create Client to open the Create Client form.
  7. Complete the Create Client form.
    FieldDescription
    Client IDSpecify a name for the OAuth2 client you are creating.
    Authorized Grant TypesChoose one or more of the following grant types:
    • authorization_code

      When you use the authorization code grant type, the client directs the resource owner to UAA, which in turn directs the resource owner back to the client with the authorization code.

    • client_credentials

      When you use the client credentials grant type, the OAuth2 endpoint in UAA accepts the client ID and client secret and provides Access Tokens.

    • password

      When you use the resource owner password credentials grant type, the OAuth2 endpoint in UAA accepts the username and password and provides Access Tokens.

    • refresh_token

      The refresh tokens are credentials used to obtain access tokens. You can choose this option to obtain refresh token from UAA. You can then use the refresh token to obtain a new access token from UAA when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.

    • implicit

      When you use the implicit grant type, UAA directly issues an Access Token to the client without authenticating the client. This reduces the number of round trips required to obtain an access token.

    For more information on grant types, see RFC 6749.

    Client SecretSpecify the password. It is important that you keep a note of this password. If lost, this password cannot be retrieved.
    Confirm Client SecretReenter the client secret.
    Redirect URISpecify a redirect URI to redirect the client after login or logout (for example, http://example-app.com/callback). Use this URI when you start using UAA as the service provider for your external Identity provider. UAA uses the value of Redirect URI for /oauth/authorize and /logout endpoints.

    You must specify a Redirect URI value if you use the Authorization Code or Implicit authorization grant type. When you use the Authorization Code grant type, the Redirect URI is your application's endpoint or callback that expects user authorization code. When you use the Implicit grant type, the Redirect URI is the end point where UAA sends the bearer token.

    Unique Resource Identifier consists of:
    • Access Protocol, http or https
    • Domain or IP address
    • Access Port such as 80 or 443
    • Path

    If you have a specific URL for your application callback, you can use that to set the Redirect URI value for the related client. For example, https://your-app-domain.run.aws-usw02-pr.ice.predix.io/path1/path2/callback.

    You can specify multiple values for Redirect URI as a list of allowed destinations that UAA server can redirect the users. For example, https://yourappdomain1.run.aws-usw02-pr.ice.predix.io/path1/path2/callback, https://yourappdomain2.run.aws-usw02-pr.ice.predix.io/path1/path2/callback.

    If the subdomain of your application is dynamic, you can set the value of Redirect URI using wilcards. For example, https://*.your-app-domain.run.aws-usw02-pr.ice.predix.io/path1/path2/callback.

    Note: You must only use ‘*’ for a domain that is exclusive to your application (Such as your-app-domain in example above). This prevents the redirect to be routed to an application that you do not own. You cannot use * in the top domain and sub domain (such as predix.io in the example above).
    ScopesScopes are permissions associated with an OAuth Client to determine user access to a resource through an application. The user permissions are for authorization grant types authorization_code, password and implicit.

    By default, the admin client is assigned all required scopes. For a new client, an administrator can select the scopes to be added based on client requirements.

    For a list of available scopes, see Scopes Authorized by the UAA.

    To use an OAuth2 client for your Predix Platform service instance, you must update your OAuth2 client to add scopes that are specific to each service after adding the client to the service instance.

    AuthoritiesAuthorities are permissions associated with the OAuth Client when an application or API is acting on its own behalf to access a resource with its own credentials, without user involvement. The permissions are for the client_credentials authorization grant type.

    By default, the admin client is assigned all required authorities. For a new client, an administrator can select the authorities to be added based on client requirements.

    The list of authorities matches the list of scopes. For a list of available UAA scopes, see Scopes Authorized by the UAA.

    To use an OAuth2 client for your Predix Platform service instance, you must update your OAuth2 client to add authorities that are specific to each service after adding the client to the service instance.

    Note: An admin client is not assigned the default authority to change the user password. To change the user password, you must add the uaa.admin authority to your admin client.
    Auto Approved ScopesSpecify scopes that can be approved automatically for the client without explicit approval from a resource owner.
    Allowed ProvidersSpecifies the names of the external identity providers, if any. This field is required if you are using external identity providers with UAA as a service provider.
    Access Token ValiditySpecifies the access-token expiration time in ms.
    Refresh Token ValiditySpecifies the refresh-token expiration time in ms.

What to do next

t_updating_oauth2_client.html#task_k3h_k2c_1x for your service specific information.