Identity Provider Configuration

Identity providers in DevOps Secrets Safe are responsible for performing authentication and assigning identity to authenticated users. Only the internal identity provider is enabled by default. External identity providers can be configured to enable usage of identity sources separate from the internal user store.

Manage Identity Providers

Identity providers can be configured using the CLI or the API. Management permissions for identity provider configurations are CRUD operations the resource path /principal. Once configured, the base resource path for an identity provider is /principal/<providerName>. The internal identity provider exists at the path /principal/internal.

Users can attempt authentication via the provider using the route /connect/token/<providerName>. For example, if a provider were configured with the name "developers", principals from that provider would exist under the path principal/developers while users from that provider could log in by supplying their credentials in a request to the route /connect/token/developers.

Principals are created for external users the first time they successfully log in. It is not currently possible to set up permissions for specific users from external identity providers until they first perform a login. The act of logging in makes DevOps Secrets Safe aware of the user identity and makes the identity eligible for permission management.

List Identity Provider Configurations

ssrun identity get

This command returns a JSON array of all external identity provider configurations.

Output

$ ssrun list-identity-providers
[
 {
   "Name": "ldap_production",
   "Type": "LDAP",
   "Options": {
     "Url": "ldap://ldap.bt.test",
     "BindDn": "uid=tesla,dc=example,dc=com",
     "BindCredentials": "password",
     "SearchBase": "dc=example,dc=com",
     "SearchFilter": "(&(objectClass=person)(uid={0}))",
     "GroupDn": "dc=example,dc=com",
     "GroupFilter": "(|(memberUid={0})(member={0})(uniqueMember={0}))"
   }
 },
 {
     "Type": "idcs_sample",
     "Name": "IDCS",
     "Options": {
         "ClientId": "abcdefg",
         "ClientSecret": "987654321",
         "InstanceUrl": "https://<siteinstance>.oraclecloud.com"
     }
 }
]

Create Identity Provider Configuration

ssrun identity create -f myConfig.txt

Creates the identity provider described in the file at myConfig.txt.

For more information about valid configuration samples, please see Supported Identity Provider Types.

Update Identity Provider Configuration

ssrun identity update -f myConfig.txt -n <providerName>

Updates the identity provider named <providerName> with the contents of the configuration file myConfig.txt. The name field for a provider is static and cannot be changed by an update operation. All other fields are eligible for modification.

Delete Identity Provider Configuration

ssrun identity delete -n <providerName>

Deletes the identity provider configuration named <providerName>. After deletion, the named provider is erased and can no longer be used for authentication. Users whose identities originate from the deleted provider will not be able to obtain new authorization tokens.

Group Membership Synchronization for External Identity Providers

DevOps Secrets Safe supports synchronization of group membership for users and groups defined in external providers.

In order for an externally-defined group to become eligible for membership synchronization, a matching representation of the group must be created in DSS using the group management API. A unique ID for the group in DSS must be provided in the group creation call and must match the unique ID for the corresponding group in the external provider.

Group membership for external users is synchronized at login-time. Users are added to and removed from groups in DevOps Secrets Safe according to the membership lists queried from the external provider at the time the user logs in.

Examples of typical group synchronization workflows for each identity provider type are described in the provider configuration description sections below.

Supported Identity Provider Types

The supported identity provider types and their required configuration fields are listed in this section. All provider configurations require the following top-level items:

  • Name - The name for the provider
  • Type - The provider type (currently either "IDCS" or "LDAP")

The configuration options specific to each provider type are described in the subsections that follow.

LDAP

Sample LDAP identity provider configuration:

{
  "Name": "ldap_production",
  "Type": "LDAP",
  "Options": {
    "Url": "ldap://ldap.bt.test",
    "BindDn": "uid=tesla,dc=example,dc=com",
    "BindCredentials": "password",
    "SearchBase": "dc=example,dc=com",
    "SearchFilter": "(&(objectClass=person)(uid={0}))",
    "GroupDn": "dc=example,dc=com",
    "GroupFilter": "(|(memberUid={0})(member={0})(uniqueMember={0}))"
  }
}
  • Url (string, required) - URL for the target LDAP server.
    • Example: ldap://secretssafe.test:389, ldaps://secretssafe.test:636
  • Certificate (string, optional) - CA certificate to use for verifying LDAP server certificate, must be x509 PEM-encoded.
  • StartTls (bool, optional) - If true, issue STARTTLS request after connection to establish TLS-secure communication on an otherwise clear-text LDAP connection.
  • InsecureTls (bool, optional) - If true, skip LDAP server SSL certificate verification - this is not secure and not recommended for production use.
  • BindDn (string, required) - Distinguished name for target bind object when performing user and group search.
  • BindCredentials (string, required) - Password to use with BindDn.
    • Example: cn=admin,dc=secretssafe,dc=test
  • SearchBase (string, required) - Base DN for user search.
    • Example: ou=users,dc=secretssafe,dc=test
  • SearchFilter (string, required) - Filter for user search. Username is inserted at the template position {0} from the string.
    • Example: (&(objectClass=person)(uid={0}))
  • GroupDn (string, required) - Base DN under which to perform group search. Example "ou=groups,dc=secretssafe,dc=test".
  • GroupFilter (string, optional) - Filter for group membership query. Username is inserted at the template position {0} from the string. Defaults to "(|(memberUid={0})(member={0})(uniqueMember={0}))"

Group membership synchronization for LDAP uses the group object's DN (Distinguished Name) as the identitfier for matching local groups to groups defined on the server. DevOps Secrets Safe queries the LDAP server using the provided GroupDn as the search base to return a collection of Group objects. The membership list for each group is then filtered using the provided GroupFilter to determine which groups the currently logging-in user is a member of.

Consider the following scenario:

An LDAP identity provider is configured in DevOps Secrets Safe with the name LDAP. A user tesla exists in the remote LDAP server, with DN: uid=tesla, ou=people, dc=secretssafe, dc=test. The user is a member of LDAP group: cn=scientists, ou=groups, dc=secretssafe, dc=test.

In order to make this group's membership eligible for synchronization with DSS, we must first use the group management API to create a group with the following parameters:

UniqueID: cn=scientists, ou=groups, dc=secretssafe, dc=test (the group's DN according to the remote server) IdentityProvider: LDAP (the configured name for this identity provider in DSS)

After that group has been created in DevOps Secrets Safe, user tesla will be added to the group's membership list the next time they perform a login to DSS. If user tesla is removed from the group on the remote LDAP server, they will be removed from the corresponding DSS group at their next login.

Examples

LDAPS Scenario

  • LDAP server running on LDAPS port 636 at ldaps://ldap.secretssafe.test:636
  • Users exist under the path ou=people,dc=secretssafe,dc=test
  • Groups exist under the path ou=groups,dc=secretssafe,dc=test
  • Bind object used for searching is cn=admin,dc=secretssafe,dc=test, with password adminpass
{
    "Type": "LDAP",
    "Name": "LDAP_tls",
    "Options": {
      "Url": "ldaps://ldap.secretssafe.test:636",
      "BindDn": "cn=admin,dc=secretssafe,dc=test",
      "BindCredentials": "adminpass",
      "SearchBase": "ou=people,dc=secretssafe,dc=test",
      "SearchFilter": "(&(objectClass=person)(cn={0}))",
      "GroupDn": "ou=groups,dc=secretssafe,dc=test",
      "GroupFilter": "(|(memberUid={0})(member={0})(uniqueMember={0}))",
      "Certificate": "MIIFrTCCA5UCFEncf+v6D0ZU6W="
    }
}

LDAP with StartTLS Scenario

  • Server running on standard LDAP port 389 at ldaps://ldap.secretssafe.test:389
  • Server expects STARTTLS command to begin encrypted communication on the standard port.
  • Users exist under the path ou=people,dc=secretssafe,dc=test
  • Groups exist under the path ou=groups,dc=secretssafe,dc=test
  • Bind object used for searching is cn=admin,dc=secretssafe,dc=test, with password adminpass
{
    "Type": "LDAP",
    "Name": "LDAP_starttls",
    "Options": {
      "Url": "ldap://ldap.secretssafe.test:389",
      "BindDn": "cn=admin,dc=secretssafe,dc=test",
      "BindCredentials": "adminpass",
      "SearchBase": "ou=people,dc=secretssafe,dc=test",
      "SearchFilter": "(&(objectClass=person)(cn={0}))",
      "GroupDn": "ou=groups,dc=secretssafe,dc=test",
      "GroupFilter": "(|(memberUid={0})(member={0})(uniqueMember={0}))",
      "InsecureTls": "false",
      "StartTls": "true",
      "Certificate": "MIIFrTCCA5UC="
    }
}

IDCS

Sample IDCS identity provider configuration:

    {
      "Name": "idcs_sample",
      "Type": "IDCS",
      "Options": {
        "ClientId": "abcdefg",
        "ClientSecret": "987654321",
        "InstanceUrl": "https://<siteinstance>.oraclecloud.com"
      }
    }

Required options for IDCS are:

  • ClientId (string, required) - IDCS client ID.
  • ClientSecret (string, required) - IDCS client secret.
  • InstanceUrl (string, required) - Base URL for the target IDCS instance.

Group membership synchronization for IDCS uses the group object's entity ID as the identitfier for matching local groups to groups defined in the remote provider. DevOps Secrets Safe uses the following IDCS API route to query group membership for a specific user:

admin/v1/Users/{userId}?attributes=groups