Managing Tokens

Using UAA for Token Validation

UAA uses token based authentication, issuing tokens for client applications to use when they act on behalf of Cloud Foundry users. Token based authentication is required to develop secure applications that can only be accessed based on a security token that is generated for the user on authentication.

After generating an Access Token, the client accessing your application presents the bearer token to your application for authentication. Your application validates this token using UAA. A token can be validated in one of the following ways:

  • Validate the token remotely using UAA

    UAA provides an endpoint (/check_token) to validate an access token coming from a resource server. For more details on the endpoint, see UAA Documentation.

  • Validate the token locally
    Predix platform provides a Java-based FastTokenService library to validate the token locally. FastTokenService performs the following tasks:
    • Downloads and caches the UAA identity zone public key and uses this key to validate the token signature.
    • Validates that the token is issued by a valid issuer.
    • Validates that the token has not expired.
    • Validates that the token is not issued for a future date.

    For more information on FastTokenService library, see uaas-managing-tokens.html#task_495fba73-59fe-41a0-a8d4-753bcf33a211.

The type of token validation that you use depends on the validation needs of your application. For example, if you need to use token revocation, then you must use remote token validation. However if you only need to validate that the token has not expired, you can validate the token locally and minimize the network request to UAA. While remote validation offers complete validation support, the local validation is much faster and less taxing on the network.

The following table shows the different scenarios where remote and local validation can be used:

Validation RequirementRemote ValidationLocal Validation
Is the token tampered?YesYes
Is the token expired?YesYes
Is the token issued for a future date?YesYes
Was the token revoked?YesNo
Is the user still available and active?YesNo
Is the token issued by UAA?YesYes
Is the issuing application still available?YesNo

Setting up Fast Token Validation

About This Task

In a typical security scenario, when your application uses UAA, the client accessing your application presents its UAA token issued for authentication. Your application redirects this token to UAA for validation. If your application requires frequent validation of these tokens, it can have an impact on the performance of the application. To mitigate this risk, you can use the Predix FastTokenService library to fetch the UAA token signing key at startup and perform the validation. The FastTokenService library is available through maven artifactory.

To use the FastTokenService library,

Procedure

  1. Add the uaa-token-lib dependency to your application POM file.
    <dependency>
        <groupId>com.ge.predix</groupId>
        <artifactId>uaa-token-lib</artifactId>
        <version>3.1.1</version>
        <type>pom</type>
    </dependency>
  2. Update your Spring configuration:
    <bean id="fasttokenServices"
            class="com.ge.predix.uaa.token.lib.FastTokenServices">
            <property name="storeClaims" value="true" />
            <property name="trustedIssuers">
                <list> 
                      <value>${issuerId}</value>
                </list>
            </property>
    </bean>

    In this example, if storeClaims is set to true, it includes all claims received from the UAA/check_token endpoint as string request parameters.

  3. Update your Spring configuration to include reference to fastTokenService.
     <oauth:resource-server id="oauth2ServiceFilter"
            token-services-ref="fasttokenServices" />
    Note:

    The Spring security configuration refers to oauth2ServiceFilter as follows:

    <http pattern="/" request-matcher="ant"
        xmlns="http://www.springframework.org/schema/security"
        disable-url-rewriting="true" use-expressions="true"
        entry-point-ref="preAuthenticationEntryPoint" create-session="stateless">
    
        <intercept-url pattern="/about" access="isFullyAuthenticated()" />
        <anonymous enabled="false" />
        <custom-filter ref="oauth2ServiceFilter" position="PREAUTH_FILTER" />
    </http>
  4. Access authenticated zoneId in your code.
    ZoneOAuth2Authentication zoneAuth = (ZoneOAuth2Authentication)
          SecurityContextHolder.getContext().getAuthentication();
          String zoneId = zoneAuth.getZoneId();

Configuring UAA to Set the Token Expiration Time

You can configure your UAA client to set the expiration time for tokens to regulate the process of token expiry.

About This Task

Depending on the authorization grant type, the tokens are assigned a default value. If needed, you can update the token expiry within a set range. To set the expiration time, you can use the Configuration tab in the UAA Dashboard.

Procedure

  1. In the Console view, select the Space where your services are located.
  2. In the Services Instances page, select the UAA instance that you need 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 Customization tab.
  6. Update the following values in the Customization page:
    FieldValue
    Access Token ValiditySpecify the time for which the access token is valid.
    Refresh Token ValiditySpecify the time for which the refresh token is valid.
  7. Click Save.

Viewing Token Details

You can use the UAA Dashboard to view the details of a token assigned to a client.

About This Task

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.
  6. Select the client for which you need to view the token details.
    The client details are displayed in the right pane. For information on how to create a new client, see uaas-managing-clients.html#task_79a81b74-552e-4f74-abfc-bd37e6adac87.
  7. In the clients details pane, select the Generate Token option.
  8. Specify the Client Secret and click Generate.
    The token details are displayed.