318b303 Oct 4, 2017
1 contributor

Users who have contributed to this file

120 lines (105 sloc) 5.21 KB

Authentication Identities

When a user authenticates with CredHub, we must establish an identity based on the provided authentication token or certificate. This identity is used by CredHub for the provision and enforcement of access control and operation logging. The following sections describe the scheme of an identity as well as the values for each component by authentication method.

Identity Scheme

Authentication identities in CredHub must capture the appropriate level of detail to distinguish the type of authentication, scope within the authority (where applicable) and primary identifier. This multi-level scheme prevents collisions between identifiers and disallows a trusted authority of a different type from issuing an identity credential that is managed by a different authority.

Scheme: auth_type:scope/primary_identifier
Example: uaa-user:zone1/2ae1621a-bb35-4bb7-946a-4761d3b16a04

  • auth_type - The auth_type identifies the type of authentication granted. For example, a uaa-user is separated from a uaa-client or mtls-app.
  • scope - Some authentication method, e.g. UAA, provide multi-tenancy in a single server. Between scopes, a user name or other identifier may be duplicated. NOTE: Scopes have not yet been implemented for any authentication types.
  • primary_identifier - This value provides the unique identifier of the authenticated user.

Primary Identifiers

Type: Mutual TLS Client Credentials - Apps

Considerations - The instance guid is the most specific identifier of an application. This identifier is specific to an individual container or instance of a deployed application. The app guid is a common identifier for all instances of an application. To align with the specificity of a service bind request and general expectation of common access between instances, the app guid is used as the primary identifier. The app guid is generated by Cloud Foundry during app creation.
Identity - app guid
Example - mtls-app:fdbeb2d4-b601-4a0d-91e8-7e38dde426f7

        Version: 3 (0x2)
        Serial Number:
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=CredHub CA
            Not Before: Mar 22 22:18:16 2017 GMT
            Not After : Mar 23 22:18:16 2017 GMT
        Subject: CN=072cae6e-988d-4738-b03c-aef009d8a4f2, OU=app:fdbeb2d4-b601-4a0d-91e8-7e38dde426f7
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (2048 bit)
                Modulus (2048 bit):
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier:
            X509v3 Authority Key Identifier:
            X509v3 Extended Key Usage:
                TLS Web Client Authentication
            X509v3 Basic Constraints: critical

Type: UAA password Grant

Considerations - The user_id is a unique static guid identifier generated by UAA when a user account is created. The user_name is also static, however, if an account is deleted, a new user may be created with the previous user_name. For this reason, the generated user_id will be used as the primary identifier.
Identity - user_id
Example - uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04

  "jti": "d86ca7f2df62293596acd9d600b8519b",
  "sub": "2ae1621a-bc35-41b7-946a-4761d3b16a04",
  "scope": [
  "client_id": "credhub_cli",
  "cid": "credhub_cli",
  "azp": "credhub_cli",
  "revocable": true,
  "grant_type": "password",
  "user_id": "2ae1621a-bb35-4bb7-946a-4761d3b16a04",
  "origin": "uaa",
  "user_name": "example_user",
  "email": "",
  "auth_time": 1484085887,
  "rev_sig": "f7810179",
  "iat": 1484085889,
  "exp": 1484085904,
  "iss": "",
  "zid": "uaa",
  "aud": [

Type: UAA client_credentials Grant

Considerations - A client_credentials grant does not provide a generated guid in the same way as a password grant. The primary identifier for this grant type is the user-specified client_id. This does not change and is guaranteed to be unique within an identity zone. A client may be deleted and a new client can reuse a previously used client_id. This risk should be understood when managing client_credential grants.
Identity - client_id
Example - uaa-client:director_to_credhub

  "jti": "676312df81df4e30bc3f48fedba050fe",
  "sub": "director_to_credhub",
  "authorities": [
  "scope": [
  "client_id": "director_to_credhub",
  "cid": "director_to_credhub",
  "azp": "director_to_credhub",
  "grant_type": "client_credentials",
  "rev_sig": "261e9e11",
  "iat": 1491348320,
  "exp": 1491351520,
  "iss": "",
  "zid": "zone1",
  "aud": [