Manage Identity Providers

This API allows you to manage identity providers. This includes operations such as retrieving information and details of all identity providers, creating new identity providers or updating them, creating SCIM tokens, etc.

1. List of all Identity Providers

The GET method returns the list of all identity providers defined in the system. 

Request Example

An example GET request for retrieving the list of all identity providers is shown here.

curl --location --request GET '{{url}}/api/identity-providers' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving the list of all identity providers is shown here.

[
    {
        "id": "1HhvrKWjoFPXvOcbJSDx",
        "name": "Britive",
        "description": "Default Identity Provider",
        "type": "DEFAULT",
        "scimProvider": "Generic",
        "ssoProvider": "Generic",
        "scimEnabled": false,
        "samlMetadata": null,
        "ssoConfig": null,
        "mfaEnabled": false,
        "apiToken": null,
        "userAttributeScimMappings": [
            ]
    },
    {
        "id": "CRU86UvbP0KlnjUUv3qO",
        "name": "Azure",
        "description": "Testing SSO & SCIM with Azure",
        "type": "SAML",
        "scimProvider": "Azure",
        "ssoProvider": "Azure",
        "scimEnabled": false,
        "samlMetadata": {
            "certificateDn": "CN=Certificate",
            "ssoUrl": "https://login.test.britive.com/saml2",
            "entityId": "https://login.test.britive.com"
        },
        "ssoConfig": {
            "acsUrl": "https://login.test.britive.com/saml2/",
            "loginUrl": "https://login.test.britive.com/sso?idp=SAMLRYGfCIiD",
            "entityId": "https://login.test.britive.com",
            "sloUrl": "https://login.test.britive.com/saml2/logout",
            "scimUrl": "https://login.test.britive.com/api/scim/v2"
        },
        "mfaEnabled": false,
        "apiToken": null,
        "userAttributeScimMappings": [
        ]
    }
]

2. Get Identity Provider Details

The GET method returns the details of the identity provider, as indicated by the id associated with an identity provider in the Britive system. 

An optional parameter that can be used in this request is name.

If the name is used as the optional parameter, the GET method returns the details of the identity provider by name, by using the identity provider name given in the path as the lookup parameter. 

Request Example

An example GET request for retrieving the details of identity providers is shown here.

curl --location --request GET '{{url}}/api/identity-providers/{{idpID}}' \
--header 'Authorization: TOKEN {{apiToken}}'

An example GET request for retrieving the details of identity provider by name, when the name is provided as the optional parameter, is shown here.

curl --location --request GET '{{url}}/api/identity-providers?name={{idpName}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving the details of identity providers is shown here.

{
    "id": "CRU86UvbP0KlnjUUv3qO",
    "name": "Azure",
    "description": "Testing SSO & SCIM with Azure",
    "type": "SAML",
    "scimProvider": "Azure",
    "ssoProvider": "Azure",
    "scimEnabled": false,
    "samlMetadata": {
    },
    "ssoConfig": {
        "acsUrl": "https://test.britive-app.com/saml2/idpresponse",
        "loginUrl": "https://test.britive-app.com/sso?idp=SAMLRYGfCIiD",
        "entityId": "https://test.britive-app.com",
        "sloUrl": "https://test.britive-app.com/saml2/logout",
        "scimUrl": "https://test.britive-app.com/api/scim/v2"
    },
    "mfaEnabled": false,
    "userAttributeScimMappings": [],
    "apiToken": null
}

3. Create Identity Provider

The POST method creates a new identity provider in the system.

Request Example

An example POST request for creating a new identity provider is shown here.

curl --location --request POST '{{url}}/api/identity-providers' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
    "name": "Test",
    "description": "Test"
}'

Response Example 

An example response of POST request for creating a new identity provider is shown here.

{
    "id": "6iwodp8kvpfn1t81uv8b",
    "name": "Test",
    "description": "Test",
    "type": "SAML",
    "scimProvider": "Generic",
    "ssoProvider": "Generic",
    "scimEnabled": false,
    "samlMetadata": null,
    "ssoConfig": null,
    "mfaEnabled": false,
    "userAttributeScimMappings": [],
    "apiToken": null
}

4. Update Identity Provider

The PATCH method updates the name, description, SSO, and SCIM provider details for the identity provider. The supported values for SSO and SCIM providers are Generic and Azure. If Azure is used for SSO and SCIM provisioning, both SSO and SCIM provider needs to be Azure.

Request Example

An example PATCH request for updating the identity provider details is shown here.

curl --location --request PATCH '{{url}}/api/identity-providers/{{idpID}}' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
    "name": "Test",
    "description": "Test",
    "scimProvider": "Azure",
    "ssoProvider": "Azure"
}'

Response Example 

The response only has headers.

5. Create an SCIM Token for an Identity Provider

The POST method creates a token used for SCIM provisioning of users and groups from the target system to the Britive system. 

When this token is created, the old token associated with the identity provider will be removed. An identity provider can have only one token at any given time. The token that is generated will be returned only once.

Note: SCIM or System for Cross-domain Identity Management is an HTTP-based protocol that enables easier management of identities in multi-domain scenarios using a standardized service. An example of SCIM is enterprise-to-cloud service provider.

The request parameters used in this method are shown in the following table:

Request Example

An example POST request for creating an SCIM provisioning token is shown here.

curl --location --request POST '/api/identity-providers/jedsuc8i79iubb4r7g8v/scim-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{token}}' \
--data-raw '{
    "tokenExpirationDays" : 90
}'

Response Example 

{
  "id": "4oejlw183d91vqx55tla",
  "name": "idp1",
  "expiresOn": "2021-03-16T05:39:59Z",
  "createdOn": "2020-12-16T05:39:59Z",
  "type": "SCIM",
  "tokenExpirationDays": 90,
  "lastAccessed": "2020-12-16T05:39:59Z",
  "status": "Active",
  "assignedTo": null,
  "token": "AAAA=",
  "createdBy": "user1"
}

6. Get SCIM Token Details

The GET method returns the SCIM token details.

Request Example

An example GET request for retrieving the SCIM token details is shown here.

curl --location --request GET '/api/identity-providers/{{id}}/scim-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the GET request for retrieving the SCIM token details is shown here. 

{
  "id": "4oejlw193d71vqx55tla",
  "name": "idp1",
  "expiresOn": "2021-01-05T05:42:00Z",
  "createdOn": "2020-12-16T05:40:00Z",
  "type": "SCIM",
  "tokenExpirationDays": 20,
  "lastAccessed": "2020-12-16T05:40:00Z",
  "status": "Active",
  "assignedTo": null,
  "token": null,
  "createdBy": "user1"
}

7. Update Token Expiration Days

The PATCH method updates the token expiration days for the existing SCIM token of an identity provider.

The request parameters used in this method are shown in the following table:

Request Example

An example PATCH request for updating SCIM token expiration days is shown here.

curl --location --request PATCH '/api/identity-providers/jedsuc8i79iubb4r7g8v/scim-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{token}}' \
--data-raw '{
    "tokenExpirationDays" : 20
}'

Response Example 

The response only has headers.

8. Get Supported SCIM Attributes

The GET method returns the list of supported SCIM attributes used for provisioning from the target system to the Britive system.

Request Example

An example GET request for retrieving the supported SCIM attributes used for provisioning from the target system is shown here.

curl --location --request GET '{{url}}/api/identity-providers/scim-attributes' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

An example response of the GET request for retrieving the supported SCIM attributes used for provisioning from the target system is shown here.

[
    "active",
    "addresses[type eq \"other\"].country",
    "addresses[type eq \"work\"].country",
    "addresses[type eq \"home\"].country",
    "addresses[type eq \"other\"].formatted",
    "addresses[type eq \"work\"].formatted",
    "addresses[type eq \"home\"].formatted",
    "addresses[type eq \"other\"].locality",
    "addresses[type eq \"work\"].locality",
    "addresses[type eq \"home\"].locality",
    "addresses[type eq \"other\"].postalCode",
    "addresses[type eq \"work\"].postalCode",
    "addresses[type eq \"home\"].postalCode",
    "addresses[type eq \"other\"].region",
    "addresses[type eq \"work\"].region",
    "addresses[type eq \"home\"].region",
    "addresses[type eq \"other\"].streetAddress",
    "addresses[type eq \"work\"].streetAddress",
    "addresses[type eq \"home\"].streetAddress",
    "displayName",
    "emails[type eq \"other\"]",
    "emails[type eq \"work\"]",
    "emails[type eq \"home\"]",
    "locale",
    "name.givenName",
    "name.familyName",
    "nickName",
    "phoneNumbers[type eq \"other\"]",
    "phoneNumbers[type eq \"pager\"]",
    "phoneNumbers[type eq \"work\"]",
    "phoneNumbers[type eq \"mobile\"]",
    "phoneNumbers[type eq \"fax\"]",
    "phoneNumbers[type eq \"home\"]",
    "preferredLanguage",
    "profileUrl",
    "timezone",
    "title",
    "userName",
    "userType",
    "costCenter",
    "department",
    "division",
    "employeeNumber",
    "manager.displayName",
    "manager.value",
    "organization"
]

9. Update SCIM Mappings for Identity Attributes

The PATCH method adds SCIM mappings for an identity provider.  When new SCIM mappings are added, the existing SCIM mappings for the identity attribute are deleted, if they are already defined.

The mandatory fields required in the request are given in the following table:

All mapping requests can be sent in the same API call.

Request Example

An example PATCH request for adding SCIM mappings for an identity provider is shown here.

curl --location --request PATCH '{{url}}/api/identity-providers/{{idpID}}/scim-attribute-mappings' \
--header 'Authorization: TOKEN {{token}}' \
--data-raw '[
    {
        "scimAttributeName": "addresses[type eq \"home\"].country",
        "builtIn": false,
        "attributeId": "HSvfZ1b74HUd7o8ai5Wo",
        "attributeName": "country",
        "op": "add"
    }
]'

Response Example 

The response only has headers.

10. Delete an Identity Provider

The DELETE method deletes the identity provider based on the id of the users associated with that identity provider. This is an irreversible operation and results in the user(s) losing access to the system.

Request Example

An example DELETE request for deleting an identity provider is shown here.

curl --location --request DELETE '{{url}}/api/identity-providers/{{idpID}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example 

The response only has headers.

11. Enable or Disable Multi-factor Authentication

The PATCH method allows you to enable or disable Multi-factor Authentication (MFA) for the root user or non-root users. 

Note: Multi-factor Authentication (MFA) is an authentication mechanism where a user or a resource needs to provide two or more credentials to authenticate its identity to gain access to a specific resource such as an application.

Request Parameters

The request parameters include:

Request Example

An example PATCH request for disabling the MFA for the root user and non-root users is shown here.

curl --location --request PATCH '{{url}}/api/identity-providers/1HhvrKWjoFPXvOcbJSDx/mfa' \
--header 'Authorization: TOKEN {{token}}' \
--data-raw '{ "mfaEnabled" : false,    "mfaEnabledRootUser" : false }'

Response Example 

This request does not return a response body.