Service Identity Federation

Service identities are non-human identities used for non-interactive use cases like automation, scripting, etc... Service identities can use authentication in the following ways:

• Static: This uses SAML 2.0 and a token for a service identity is created with a validity date.
• Federated: 
  • OpenID Connect (OIDC) 1.0. For more information, see OIDC documentation. 
  • AWS Security Token Service (STS). For more information, see AWS Identity and Access Management. 

Prerequisites for OIDC providers

You need the following information before configuring an OIDC identity provider:

• Issuer Url: This needs to be unique within a tenant. For more information about the issuer URL and how to retrieve it from the ID Token, see OIDC issuer URL documentation.
• Allowed Audience: This is a value agreed upon between a client of the OIDC provider and the OIDC provider. For more information about the audience located in ID Token, see Allowed Audience.

Prerequisites for AWS STS providers

You need to generate an AWS STS token for Britive to consume. For more information about generating AWS STS tokens, see CLI application  or GetCallerIdentity.

Creating Identity Providers

An identity provider (IdP) is a service that stores and verifies user identities. The default identity provider for any user is Britive. Create and configure IdP to trust authentication tokens using the following steps:

1. Login to Britive with administrator privileges.
2. Click Admin -> Identity Management.
3. Select the Identity Providers tab and click on ADD IDENTITY PROVIDER button.
4. Enter the name and description of the tag and click ADD IDENTITY PROVIDER  button.
5. Enter the following in Add Identity Provider window:
   1. Select Identity Provider Type:
      1. SAML: Enter Name and Description.
      2. OIDC: Enter Name, Issuer Url, and Description. Issuer Url is part of the Prerequisites for OIDC Providers.
      3. AWS STS: Enter Name and Description. You can configure only one AWS STS identity 
   2. Click Add.
6. The new identity provider is displayed in the list. Click Manage to configure the identity provider.
   1. SAML: For configuring SSO or SCIM configuration for a particular identity provider, see Identity Provider Integration Guides.
   2. OIDC: 
      1. Validation Window: The validation window starts from the time the token was issued as specified in the JWT issued at ('iat') claim. The default validation window is 30 seconds. For more information, see Validation Window.
      2. Attributes map: You can edit the list of attributes map and its values. Map the ID tokens attributes issued with the OIDC provider to Britive service identity attributes. Identity attributes can be added from the Admin -> Identity Management -> Identity Attributes tab.
      3. Allowed Audiences: Edit a list of allowed audiences.  Allowed Audiences are part of the Prerequisites for OIDC Providers.
   3. AWS STS:
      1. Validation Window: The validation window starts from the time the token is signed as specified by the x-amz-date request header in the token. For more information, see Validation Window. 
      2. Max Request Token Duration: This is the maximum token validity period that can be requested by the client. 
      3. Attributes map: You can edit the list of attributes map and its values. Map the ID tokens attributes issued with the AWS provider to Britive service identity attributes. Identity attributes can be added from the Admin -> Identity Management -> Identity Attributes tab.

Creating Service Identities

1. Login to Britive with administrator privileges.
2. Click Admin -> Identity Management.
3. Select the Service Identities tab and click on ADD SERVICE IDENTITY button.
4. Enter the following on Add Service Identity page:
   1. Enter the Name and Description of the service identity.
   2. Select the Access Type. 
      1. Static: Enter Token Validity in days. This is the duration of the workload token.
      2. Federated: 
         1. Select the identity provider from the list.
         2. Enter Token Validity in seconds. This is the duration of the workload token and depends on the type of identity provider. For more information, see Token Validity.
         3. Add Federated Attributes. These are used to map service identities that the token is for. These attributes are defined while creating/managing an identity provider.
   3. Click Add. For Static authentication, a token is created and displayed. Copy and save the token.

Token Validity

The duration of the workload token depends on the type of identity provider token being used. Each service identity when selecting the workload identity provider to associate can configure the token duration in seconds of the tokens issued by the identity provider.

• OIDC: The ID Token duration is the lesser of the duration, between the current date/time the ID token is being validated and the ID Token’s expiration date claim (exp), and the mapped service identity’s configured token duration when the OIDC provider is assigned.
• AWS STS: The AWS token validity period is determined by the lesser of the AWS identity provider configured maximum token validity period, service identity configured token duration in seconds for the assigned identity provider, and the duration between the current time the token is first validated and the expiration time in the AWS “token” if requested.

Validation Window

A validation window is configured for each workload identity provider specifying the amount of time in seconds after the workload identity token was issued/signed, the Britive app verifies the token is valid. Once verified/validated, the token is considered valid until the token validity period expires as specified in the Token Validity. 

Managing Service Identities

You can edit any Static or Federated service identity parameters. You can also switch the access by clicking the Switch Access button on the Edit page. This switches from Static to Federated or vice versa.

For static service identities, you can reset the token and change the validity of tokens from the Edit page.

For federated service identities, you can change the identity provider, token validity period, and federated attribute values.

Use case of OIDC provider

The following section describes an end-to-end use case for configuring OIDC provider, Britive service identities, and how to use it by checking out a Britive profile.

1. Create an OIDC IdP using this procedure Creating Identity Providers.
2. Create a service identity and associate it to an OIDC IdP.  See Creating Service Identities to create service identities.
3. Configure the attribute map such that ID Token's attributes are mapped to the Britive service identity. For example, Britive custom attribute OIDC subject mapped to subject claim in the ID token.
4. Enter Allowed audiences. This can be retrieved from the ID Token of an OIDC provider. See the Prerequisites section for details.
5.  Get Federated Attributes. For example, user name and repository name, and branch for GitHub example.
6. Create a profile for an AWS application. Add a service identity in that policy to get access to checkout that profile.  Profile -> Permissions -> Policy -> Add service identities. For more information, see Managing Profiles.
7. When calling Britive APIs with OIDC providers, make sure to use the OIDC token prefix in the authorization header Authorization: OIDC::{{ID Token}}.
   

Use case of AWS STS provider

The following section describes an end-to-end use case for configuring AWS STS provider, Britive service identities, and how to use it by checking out a Britive profile.

1. Create AWS STS identity provider using this procedure Creating Identity Providers.
2. Create a service identity and associate it with AWS STS identity provider.  See Creating Service Identities to create service identities.
3. Configure the attribute map such that ID Token's attributes are mapped to the Britive service identity.  Map Account, Arn, and UserId from the ID token to Britive custom attributes. For more information on how to retrieve attributes from the token, GetCallerIdentity.
4. Create a profile for an AWS application. Add a service identity in that policy to get access to checkout that profile.  Profile -> Permissions -> Policy -> Add service identities. For more information, see Managing Profiles.
5. When calling Britive APIs with OIDC providers, make sure to use the OIDC token prefix in the authorization header Authorization: AWS::{{ID Token}}.