Identity Provider APIs

Use Identity Provider(IdP) APIs to register IdP configuration and their connections.

It is a mandatory step in the following scenarios:

Note:

Register IdP

You can register the IdP by the following methods:

SAML with SCIM dependency registration

The following example shows the IdP registration with ISV (IBM Security Verify) which supports SCIM enabled IdP with SAML. Hence, the token_attribute_mappings and scim_attribute_mappings can be different for the respective IdPs.

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/
Command
POST
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V2.

The sample curl command resembles the following code:

curl -k -X POST 'https://cp-console.apps.cp.fyre.ibm.com/idprovider/v2/auth/idsource/registration' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
    "name": "idp_saml_isv",
    "description": "This is a saml isv config",
    "protocol": "saml",
    "idp_type": "isv",
    "scim": "yes",
    "scim_base_path": "https://bedrock-iam.verify.ibm.com/v2.0/",
    "token_attribute_mappings": {"uid":"userID","first_name":"given_name","last_name":"family_name", "groups": "groupIds", "email":"email"},
    "jit": "no",
    "scim_attribute_mappings":{
         "user":{
         "principalName":"userName",
         "givenName":"name.givenName",
         "middleName":"name.middleName",
         "familyName":"name.familyName",
         "formatted":"name.formatted"
         },
         "group":{
          "principalName":"displayName",
          "created":"meta.created",
          "lastModified":"meta.lastModified"
         }
    },
    "config": {
        "grant_type": "client_credentials",
        "token_url": "https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token",
        "client_id": "c2eae9d2-900d-4102-840b-023af12e36c5",
        "client_secret":"Your_isv_client_id"
    },
    "status": "enabled"
}'

The response resembles the following code:

{"status":"Client Successfully registered."}

The error message resembles the following code:

400 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
201 OK Response

SAML registration without any dependency

The following example shows the IdP registration by using SAML without any dependency:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/
Command
POST
Command output format
application/json

Note:

The following sample curl command shows the SAML registration with w3id SAML provider:

curl -k -X POST 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/idprovider/v2/auth/idsource/registration' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
    "name": "w3id-sample-saml",
    "description": "w3id-sample-saml-test",
    "protocol": "saml",
    "idp_type": "default",
    "scim": "no",
    "saml_ldap": "None",
    "jit": "yes",
    "token_attribute_mappings": {"uid": "uid","first_name": "firstName","last_name": "lastName", "groups": "blueGroups", "email": "emailAddress"},
    "status": "enabled"
}'

The response resembles the following code:

{"status":"Client Successfully registered."}

The sample registration for configuring Azure AD with auto-onboarding:

curl -k -X POST 'https://cp-console.apps.cp.fyre.ibm.com /idprovider/v2/auth/idsource/registration' \ --header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
    "name": "idp_saml_azure",
    "description": "This is a saml azure config",
    "protocol": "saml",
    "idp_type": "default",
    "jit": "yes",
    "saml_ldap": "None",
    "token_attribute_mappings": {
            "uid": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
            "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
            "last_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
            "groups": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
            "email": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
    },
    "status": "enabled"
}'

The error message resembles the following code:

400 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
201 OK Response

SAML with LDAP dependency registration

The following example is provided for IBM W3 SAML Provider and with dependency of an IBM Tivoli Directory Server LDAP. The token_attribute_mappings might change based on the SAML provider.

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/
Command
POST
Command output format
application/json

Note:

The sample curl command resembles the following code:

curl -k -X POST 'https://cp-console.apps.cp.fyre.ibm.com/idprovider/v2/auth/idsource/registration' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
    "name": "saml-test",
    "description": "saml bluepages with ldap",
    "protocol": "saml",
    "idp_type": "default",
    "saml_ldap":"IBM Tivoli Directory Server",
    "token_attribute_mappings": {"uid":"uid", "first_name":"firstName", "last_name":"lastName", "groups": "blueGroups","email":"email"},
    "jit": "no",
    "status": "enabled"
}'

The response resembles the following code:

{"status":"Client Successfully registered."}

The error message resembles the following code:

400 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
201 OK Response

Get IdP registration

You can get the IdP registration by the following ways:

Get IdP registration by name

The following example shows how to get the details of IdP registration by name:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/idpname
Command
GET
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V2.

The sample curl command resembles the following code:

curl -k -X GET 'https://cp-console.apps.mycluster.mydomain.com/idprovider/v2/auth/idsource/registration/isvbedrock-test' \
--header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
    "name": "isvbedrock-test",
    "description": "ISV bedrock test ISV",
    "protocol": "saml",
    "idp_type": "isv",
    "scim": "yes",
    "scim_base_path": "https://bedrock-iam.verify.ibm.com/v2.0/",
    "token_attribute_mappings": {
        "uid": "userID",
        "first_name": "given_name",
        "last_name": "family_name",
        "groups": "groupIds",
        "email": "email"
    },
    "jit": "no",
    "scim_attribute_mappings": {
        "user": {
            "principalName": "userName",
            "givenName": "name.givenName",
            "middleName": "name.middleName",
            "familyName": "name.familyName",
            "formatted": "name.formatted"
        },
        "group": {
            "principalName": "displayName",
            "created": "meta.created",
            "lastModified": "meta.lastModified"
        }
    },
    "config": {
        "grant_type": "client_credentials",
        "token_url": "https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token",
        "client_id": "c2eae9d2-900d-4102-840b-023af12e36c5"
    },
    "status": "enabled"
}

The error message resembles the following code:

403 "error": "Insufficient user permission for role : rolename"
404 "error": "Document not found"
500 "error": "Other errors"
200 OK Response

Get the list of IdP registration

The following example shows how to get the list of IdP registration:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration
Command
GET
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V2.

The sample curl command resembles the following code:

curl -k -X GET 'https://cp-console.apps.cp.fyre.ibm.com/idprovider/v2/auth/idsource/registration' \
---header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
"idp": [
        {
            "name": "isvbedrock-test",
            "description": "ISV bedrock test ISV",
            "protocol": "saml",
            "idp_type": "isv",
            "scim": "yes",
            "scim_base_path": "https://bedrock-iam.verify.ibm.com/v2.0/",
            "token_attribute_mappings": {
                "uid": "userID",
                "first_name": "given_name",
                "last_name": "family_name",
                "groups": "groupIds",
                "email": "email"
            },
            "jit": "no",
            "scim_attribute_mappings": {
                "user": {
                    "principalName": "userName",
                    "givenName": "name.givenName",
                    "middleName": "name.middleName",
                    "familyName": "name.familyName",
                    "formatted": "name.formatted"
                },
                "group": {
                    "principalName": "displayName",
                    "created": "meta.created",
                    "lastModified": "meta.lastModified"
                }
            },
            "config": {
                "grant_type": "client_credentials",
                "token_url": "https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token",
                "client_id": "c2eae9d2-900d-4102-840b-023af12e36c5"
            },
            "status": "enabled"
        }
    ]
}

The error message resembles the following code:

403 "error": "Insufficient user permission for role : rolename"
500 "error": "Other errors"
200 OK Response

Get IdP registration by query

The following example shows how to get the IdP registration by query:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/
Command
GET
Command output format
application/json

The sample curl command resembles the following code:

curl -k -X GET 'https://cp-console.apps.iam-test.cp.fyre.ibm.com/idprovider/v2/auth/idsource/registration?idp_type=isv' \
--header "Authorization: Bearer $ACCESS_TOKEN"

You can also alter the query based on the requirements. For example,

curl -k -X GET 'https://cp-console.apps.mycluster.mydomain.com/idprovider/v2/auth/idsource/registration?name=isvbedrock-test' \
--header "Authorization: Bearer $ACCESS_TOKEN"

curl -k -X GET 'https://cp-console.apps.mycluster.mydomain.com/idprovider/v2/auth/idsource/registration?protocol=saml \
--header "Authorization: Bearer $ACCESS_TOKEN"

Note: The code contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V2.

The response resembles the following code:

    "idp": [
        {
            "name": "isvbedrock-test",
            "description": "ISV bedrock test ISV",
            "protocol": "saml",
            "idp_type": "isv",
            "scim": "yes",
            "scim_base_path": "https://bedrock-iam.verify.ibm.com/v2.0/",
            "token_attribute_mappings": {
                "uid": "userID",
                "first_name": "given_name",
                "last_name": "family_name",
                "groups": "groupIds",
                "email": "email"
            },
            "jit": "no",
            "scim_attribute_mappings": {
                "user": {
                    "principalName": "userName",
                    "givenName": "name.givenName",
                    "middleName": "name.middleName",
                    "familyName": "name.familyName",
                    "formatted": "name.formatted"
                },
                "group": {
                    "principalName": "displayName",
                    "created": "meta.created",
                    "lastModified": "meta.lastModified"
                }
            },
            "config": {
                "grant_type": "client_credentials",
                "token_url": "https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token",
                "client_id": "c2eae9d2-900d-4102-840b-023af12e36c5"
            },
            "status": "enabled"
        }
    ]
}

The error message resembles the following code:

403 "error": "Insufficient user permission for role : rolename"
500 "error": "Other errors"
200 OK Response

Updating IdP

To update the IdP registration, you require the IdP name. To get the IdP name, see Get the list of IdP registration. The following example shows how to update the IdP registration:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/
Command
PUT
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V2.

The sample curl command resembles the following code:

curl -k -X PUT 'https://cp-console.apps.sashay.cp.fyre.ibm.com/idprovider/v2/auth/idsource/registration/saml-test' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
    "name": "saml-test",
    "description": "saml bluepages no ldap",
    "protocol": "saml",
    "idp_type": "default",
    "saml_ldap":"Custom",
    "token_attribute_mappings": {"uid":"uid", "first_name":"firstName", "last_name":"lastName", "groups": "blueGroups","email":"email"},
    "jit": "no",
    "status": "enabled"
}  '

The response resembles the following code:

{"status":"Client Successfully updated."}

The error message resembles the following code:

400 "error": "Insufficient user permission for role : rolename"
400 "error": "schema constraint error: schema validation error followed by error"
500 "error": "Other errors"
202 OK Response

Deleting IdP registration

To delete the IdP registration, you require the IdP name. To get the IdP name, see Get the list of IdP registration. The following example shows how to delete the IdP registration:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v2/auth/idsource/registration/
Command
DELETE
Command output format
application/json

The sample curl command resembles the following code:

curl -k -X DELETE 'https://cp-console.apps.cp.fyre.ibm.com/idprovider/v2/auth/idsource/registration/saml-test'  \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{"status":"Client Successfully deleted.”}

The error message resembles the following code:

400 "error": "Insufficient user permission for role : rolename"
404 "error": "Document not found"
500 "error": "Other errors"
202 OK Response

IdP V3 APIs

From foundational services version 3.19.9 and later, you can register OIDC and SAML providers with the IdP V3 API. To register OIDC and SAML provider using IdP V3, see Registering the OIDC clients using IdP V3 and Registering the SAML clients using IdP V3.

It is recommended to configure the SAML from your product UI. For more information, see Configuring single sign-on using your product UI.

Registering the OIDC clients using IdP V3

Before you begin

Login to any of the following platforms by using the provided IdP links and register yourself in the application. While registering, use application url as cp-console url and redirect URL as https://<cp-console-url>/ibm/api/social-login/redirect/<name of the oidc>. Once you are registered, you can get the unique client ID, client secret and discovery_url endpoint. Currently, only these platforms are verified to register the OIDC by using the IdP V3 API.

Verified platforms to register OIDC provider using IdP V3
Platform IdP link
IBM Security Verify https://www.ibm.com/docs/en/erqa?topic=using-security-verify-as-oidc-provider
Note: Whenever you perform the attributes mapping through the OIDC provider in the ISV application, enable the Send all known user attributes in the ID token option. And, ISV groups must not contain spaces.
Google Cloud Platform https://cloud.google.com/identity-platform/docs/web/google
Microsoft https://cloud.google.com/identity-platform/docs/web/microsoft
Okta https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm

Note: The IdP links for the listed verified platforms can be changed anytime by their service providers. If any of the listed IdP links are broken, check the IdP links on their official websites.

Registering the OIDC clients

The following example shows how to register the client by using IdP V3:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster address
Port number
Cluster Port
Path
idprovider/v3/auth/idsource
Command
POST
Command output format
application/json

Note:

The sample curl command to register the client:

curl --insecure POST 'https://cp-console.apps.vij-soc.cp.fyre.ibm.com/idprovider/v3/auth/idsource/'
--header "Authorization: Bearer $ACCESS_TOKEN"
--header 'Content-Type: application/json'
--data-raw
'{
    "name": "oidc_isv",
    "description": "This is a oidc config for isv",
    "protocol": "oidc",
    "type": "IBMVerify",
    "idp_config": {
        "discovery_url": "https://bedrock-iam.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration",
        "client_id": "4ad41ddc-5f10-4d84-a24f-fb776607895e",
        "client_secret": "rqJMyEgee",
        "token_attribute_mappings": {
            "groups": "groupIds",
            "given_name": "given_name",
            "family_name": "family_name",
            "sub": "uid",
            "email": "email"
        }
    }
}'

The response resembles the following code:

{
    "status": "success",
    "message": "Identity provider {oidc_isv} is successfully registered with unique identifier NpiV6qBhsSDEjKRvJDQLl"
}

The error message resembles the following code:

400 "error":  "E11000 duplicate key error collection: platform-db.cloudpak_ibmid_v3 index: name_1 dup key: { : <oidc name>" }"
500 "error": "Other errors"
401 "error": "Insufficient user permission for role :Viewer"
202 OK Response

Deleting the registration of the client

The following example shows how to delete the registered client by using IdP V3:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster address
Port number
Cluster Port
Path
idprovider/v3/auth/idsource/
Command
DELETE
Command output format
application/json

The sample curl command to delete the client registration:

curl --insecure DELETE 'https://cp-console.apps.vij-soc.cp.fyre.ibm.com/idprovider/v3/auth/idsource/NpiV6qBhsSDEjKRvJDQLl' --header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
“status”: “success”,
“message”: “{NpiV6qBhsSDEjKRvJDQLl} is deleted”
}

The error message resembles the following code:

400 "error": "Cannot find {oidc uid}"
401 "error": "Insufficient user permission for role :Viewer"
200: Ok Response

Getting the list of registered OIDC clients

You can get the list of registered OIDC clients by using either of the following methods:

Getting the list of registered OIDC clients by UID

The following example shows how to get the list of all the registered clients by UID:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/
Command
GET
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The following sample curl command to get the list of registered clients by UID:

curl --insecure --request GET 'https://cp-console.cp.fyre.ibm.com/idprovider/v3/auth/idsource/yOLi5oHo3t-es4aJFLkC8' --header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
  "name": "oidc_1",
  "description": "This is a oidc config",
  "protocol": "oidc",
  "type": "IBMVerify",
  "idp_config": {
    "discovery_url": "https://bedrock-iam.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration",
    "client_id": "My_Client_ID",
    "client_secret": "My_Client_Secret",
    "token_attribute_mappings": {
      "groups": "groupIds"
    }
  },
  "uid": "NpiV6qBhsSDEjKRvJDQLl"
}

The error message resembles the following code:

400 "error": "Cannot find {oidc uid}"
401 "error": "Insufficient user permission for role :Viewer"
200: Ok Response

Getting the list of registered OIDC clients by query

The following example shows how to get the list of all the registered clients by query:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/
Command
GET
Command output format
application/json

The following sample curl command to get the list of registered clients by query:

curl --insecure --request GET 'https://cp-console.cp.fyre.ibm.com/idprovider/v3/auth/idsource?protocol=oidc' --header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
    "idp": [
        {
            "name": "oidc_google",
            "description": "This is a oidc config for google",
            "protocol": "oidc",
            "type": "google",
            "idp_config": {
                "discovery_url": "https://accounts.google.com/.well-known/openid-configuration",
                "client_id": "My_Client_ID",
                "client_secret": "My_Client_Secret",
                "token_attribute_mappings": {
                    "groups": "groupIds",
                    "given_name": "firstName",
                    "family_name": "lastName",
                    "sub": "uid",
                    "email": "email",
                    "uniqueSecurityName": "uniqueSecurityName"
                }
            },
            "uid": "Uo4Y31mV7unaj5NtyfpIY"
        },
        {
            "name": "oidc_isv",
            "description": "This is a oidc config",
            "protocol": "oidc",
            "type": "IBMVerify",
            "idp_config": {
                "discovery_url": "https://bedrock-iam.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration",
                "client_id": "My_Client_ID",
                "client_secret": "My_Client_Secret",
                "token_attribute_mappings": {
                    "groups": "groupIds",
                    "given_name": "given_name",
                    "family_name": "family_name",
                    "sub": "uid",
                    "email": "email",
                    "uniqueSecurityName": "uniqueSecurityName",
                    "preferred_username": "preferred_username",
                    "displayName": "displayName"
                }
            },
            "uid": "NpiV6qBhsSDEjKRvJDQLl"
        }
    ]
}

The error message resembles the following code:

400 "error": "Cannot find {oidc uid}"
401 "error": "Insufficient user permission for role :Viewer"
200: Ok Response

Updating the OIDC clients

The following example shows how to update the OIDC client by using IdP V3:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster address
Port number
Cluster Port
Path
idprovider/v3/auth/idsource
Command
PUT
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The sample curl command to update the client:

curl --insecure PUT 'https://cp-console.cp.fyre.ibm.com/idprovider/v3/auth/idsource/NpiV6qBhsSDEjKRvJDQLl'
--header "Authorization: Bearer $ACCESS_TOKEN"
--header 'Content-Type: application/json'
--data-raw
'{
    "name": "oidc_isv",
    "description": "This is a oidc config for isv",
    "protocol": "oidc",
    "type": "IBMVerify",
    "idp_config": {
        "discovery_url": "https://bedrock-iam.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration",
        "client_id": "4ad41ddc-5f10-4d84-a24f-fb776607895e",
        "client_secret": "rqJMyEgee",
        "token_attribute_mappings": {
            "groups": "groupIds",
            "given_name": "given_name",
            "family_name": "family_name",
            "sub": "uid",
            "email": "email"
        }
    }
}'

The response resembles the following code:

{
    "status": "success",
    "message": "{NpiV6qBhsSDEjKRvJDQLl} is Updated."
}

The error message resembles the following code:

400 "error": "Document not found"
401 "error": "Insufficient user permission for role :Viewer"
200: Ok Response

Registering the SAML clients using IdP V3

You can register the SAML IdP by the following methods:

Note: You can configure only one SAML registration at an instance. The unique identifier generated on the POST request is defaultSP. For idp_metadata, you need to provide base64 encoded value of the generated identity provider metadata xml file.

Get the base64 encoded value of generated identity provider metadata xml file by using the following code:

cat idp-metadata-xml |base64

SAML with SCIM dependency registration (IdP V3 registration with IBM Security Verify and Okta)

IdP V3 registration with IBM Security Verify (ISV)

The following example shows the IdP V3 registration with ISV that supports SCIM enabled IdP with SAML. Hence, the token_attribute_mappings and scim_attribute_mappings can be different for the respective IdPs.

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/registration/
Command
POST
Command output format
application/json

Note:

The sample curl command resembles the following code:

curl --insecure POST 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/idprovider/v3/auth/idsource'
--header "Authorization: Bearer $ACCESS_TOKEN"
--header 'Content-Type: application/json'
--data-raw
'{
  "name": "idp_saml_isv",
  "description": "This is a saml isv config",
  "protocol": "saml",
  "type": "isv",
  "idp_config": {
    "token_attribute_mappings": {
      "sub": "userID",
      "given_name": "given_name",
      "family_name": "family_name",
      "groups": "groupIds",
      "email": "email"
    },
    "idp_metadata": "<base64-encoded-idp-xml>"
  },
  "scim_config": {
    "scim_base_path": "https://bedrock-iam.verify.ibm.com/v2.0/",
    "grant_type": "client_credentials",
    "token_url": "https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token",
    "client_id": "Your_isv_client_id",
    "client_secret": "Your_isv_client_secret",
    "scim_attribute_mappings": {
      "user": {
        "principalName": "userName",
        "givenName": "name.givenName",
        "middleName": "name.middleName",
        "familyName": "name.familyName",
        "formatted": "name.formatted"
      },
      "group": {
        "principalName": "displayName",
        "created": "meta.created",
        "lastModified": "meta.lastModified"
      }
    }
  },
  "jit": "false"
}'

The response resembles the following code:

{
    "status": "success",
    "message": "Identity provider {idp_saml_isv} is successfully registered with unique identifier defaultSP"
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
200 OK Response

IdP V3 registration with Okta

The following example shows the IdP V3 registration with Okta.

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/registration/
Command
POST
Command output format
application/json

Note:

curl --location --request POST 'https://cpconsoleroute/idprovider/v3/auth/idsource' \
--header 'Authorization: Bearer $accessToken' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "OKTASAML",
            "description": "OKTASAML",
            "protocol": "saml",
            "type": "okta",
            "idp_config": {
                "token_attribute_mappings": {
                    "sub": "uid",
                    "given_name": "firstName",
                    "family_name": "lastName",
                    "groups": "groups",
                    "email": "emailAddress",
                    "first_name": "firstName",
                    "last_name": "lastName"
                },
                "idp_metadata": "Base64-encoded-metadata"
            },
            "jit": false,
            "scim_config": {
                "redirect_url": ["okta_redirect_url"],
                "scim_attribute_mappings": {
                    "user": {
                        "principalName": "userName",
                        "name": {
                            "givenName": "givenName",
                            "familyName": "familyName"
                        },
                        "displayName": "displayName",
                        "emails": [
                            {
                                "value": "emails",
                                "type": "home"
                            }
                        ],
                        "id": "id",
                        "userName": "userName"
                    },
                    "group": {
                        "principalName": "displayName",
                        "id": "displayName"
                    }

                }
            }
        }'

The response resembles the following:

{
    "status": "success",
    "message": "Identity provider {oktasaml} is successfully registered with unique identifier : defaultSP , oktaclient created with clientId: yx3a5pwtdrmn0sf8ockyf97dg55lswo7 , client secret: okta-oidcclient-secret"
}

The error message resembles the following:

401 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
200 OK Response

token_attribute_mappings: token_attribute_mappings is a custom mapping that user can provide based on the SAML attribute mapping that is configured at Okta. User should modify the values, not the key, based on the Okta SAML attribute configuration. For more information about attributes, see Step 9 in Configure CloudPak as SAML service provider (SP) at OKTA.

For more information, see Okta doc for SAML attributes.

scim_attribute_mappings: Provide the mapping attributes as in the CURL command. The defined mapping will be used for filter query, creating attributes and the response to be sent.

redirect_url: redirect_url is only applicable for the IdP "type": "okta". The redirect_url is used to create the OIDC client registration for the OKTA instance. To get the redirect_url while using non IBM OIN App:

Based on the environment (a standard org, an EMEA org, and an Okta Preview org), the redirect_uri can be one of the following:

SAML registration without any dependency

The following example shows the IdP V3 registration by using SAML without any dependency:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/registration/
Command
POST
Command output format
application/json

Note:

The following sample curl command shows the SAML registration with w3id SAML provider:

curl -k -X POST 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/ idprovider/v3/auth/idsource' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
  "name": "w3id-sample-saml",
  "description": "w3id-sample-saml-test",
  "protocol": "saml",
  "type": "default",
  "idp_config": {
    "token_attribute_mappings": {
      "sub": "uid",
      "given_name": "firstName",
      "family_name": "lastName",
      "groups": "blueGroups",
      "email": "emailAddress"
    },
    "idp_metadata": "<base64-encoded-idp-xml>"
  },
  "jit": true
}'

The response resembles the following code:

{
    "status": "success",
    "message": "Identity provider {w3id-sample-saml} is successfully registered with unique identifier defaultSP"
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
200 OK Response

SAML with LDAP dependency registration

The following example is provided for IBM W3 SAML Provider and with dependency of an IBM Tivoli Directory Server LDAP. The token_attribute_mappings might change based on the SAML provider.

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/registration/
Command
POST
Command output format
application/json

Note:

The sample curl command resembles the following code:

curl -k -X POST 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/idprovider/v3/auth/idsource' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
'{
  "name": "saml-test",
  "description": "saml bluepages with ldap",
  "protocol": "saml",
  "type": "default",
  "idp_config": {
    "token_attribute_mappings": {
      "sub": "uid",
      "given_name": "firstName",
      "family_name": "lastName",
      "groups": "blueGroups",
      "email": "email"
    },
    "idp_metadata": "<base64-encoded-idp-xml>"
  },
  "ldap_config": {
    "ldap_id": "<existing_ldap_id>"
  },
  "jit": false
}'

The response resembles the following code:

{
    "status": "success",
    "message": "Identity provider {saml-test} is successfully registered with unique identifier defaultSP"
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
400 "error": "schema error:schema validation error followed by error"
400 "error": "duplicate : Idp with protocol=saml is already created"
500 "error": "Other errors"
200 OK Response

Getting SAML registration by UID

You can get the IdP registration by the following ways:

Getting IdP V3 registration by name

The following example shows how to get the details of IdP V3 registration by name:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource/defaultSP
Command
GET
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The sample curl command resembles the following code:

curl -k -X GET 'https://cp-console.apps.mycluster.mydomain.com/idprovider/v3/auth/idsource/defaultSP' \
--header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
    "name": "w3id-sample-saml",
    "description": "w3id-sample-saml-test",
    "protocol": "saml",
    "type": "default",
    "idp_config": {
        "token_attribute_mappings": {
            "sub": "uid",
            "given_name": "firstName",
            "family_name": "lastName",
            "groups": "blueGroups",
            "email": "emailAddress"
        },
        "idp_metadata": "<base64-encoded-idp-xml>"
    },
    "jit": true,
    "uid": "defaultSP"
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
404 "error": "Cannot find {defaultSP}
500 "error": "Other errors"
200 OK Response

Getting the list of IdP V3 registration

The following example shows how to get the list of IdP V3 registration:

Note: This API returns all registered IdPs of SAML or OIDC clients through IdP V3 API.

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource
Command
GET
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The sample curl command resembles the following code:

curl -k -X GET ‘https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/idprovider/v3/auth/idsource' \
--header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
    "idp": [
        {
            "name": "w3id-sample-saml",
            "description": "w3id-sample-saml-test",
            "protocol": "saml",
            "type": "default",
            "idp_config": {
                "token_attribute_mappings": {
                    "sub": "uid",
                    "given_name": "firstName",
                    "family_name": "lastName",
                    "groups": "blueGroups",
                    "email": "emailAddress"
                },
                "idp_metadata": "<base64-encoded-idp-xml>"
            },
            "jit": true,
            "uid": "defaultSP"
        }
    ]
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
500 "error": "Other errors"
200 OK Response

Getting SAML registration by query

The following example shows how to get the IdP V3 registration by query:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource
Command
GET
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The sample curl command resembles the following code:

curl -k -X GET 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/idprovider/v3/auth/idsource?protocol=saml'
\
--header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
    "idp": [
        {
            "name": "w3id-sample-saml",
            "description": "w3id-sample-saml-test",
            "protocol": "saml",
            "type": "default",
            "idp_config": {
                "token_attribute_mappings": {
                    "sub": "uid",
                    "given_name": "firstName",
                    "family_name": "lastName",
                    "groups": "blueGroups",
                    "email": "emailAddress"
                },
                "idp_metadata": "<base64-encoded-idp-xml>"
            },
            "jit": true,
            "uid": "defaultSP"
        }
    ]
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
500 "error": "Other errors"
200 OK Response

Updating SAML registration

To update the SAML registration, you require the IdP UID. To get the IdP UID, see Get the list of IdP V3 registration. Alternatively, you can use the UID as defaultSP because only one SAML registration at an instance is supported for now. The following example shows how to update the IdP registration:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource
Command
PUT
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The sample curl command resembles the following code:

curl -k -X PUT 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/ idprovider/v3/auth/idsource/defaultSP' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"
--data-raw
' {
  "name": "w3id-sample-saml",
  "description": "this is plain saml testing",
  "protocol": "saml",
  "type": "default",
  "idp_config": {
    "token_attribute_mappings": {
      "sub": "uid",
      "given_name": "firstName",
      "family_name": "lastName",
      "groups": "blueGroups",
      "email": "emailAddress"
    },
    "idp_metadata": "<base64-encoded-idp-xml>"
  },
  "jit": true
}'

The response resembles the following code:

{
    "status": "success",
    "message": "{defaultSP} is Updated."
}

The error message resembles the following code:

401 "error": "Insufficient user permission for role : rolename"
400 "error": "schema validation error:followed by error"
500 "error": "Other errors"
200 OK Response

Deleting SAML registration

To delete the SAML registration, you require the IdP UID. To get the IdP UID, see Get the list of IdP V3 registration. Alternatively, you can use the UID as defaultSP because only one SAML registration at an instance is supported for now. The following example shows how to delete the IdP registration:

API version
1.0.0
API URI components
Scheme
HTTPS
Host IP
Cluster Master Host
Port number
Cluster Master API Port
Path
idprovider/v3/auth/idsource
Command
DELETE
Command output format
application/json

Note: The curl command contains different schema elements. To understand the use of these schema elements, see Different schema elements for IdP V3.

The sample curl command resembles the following code:

curl -k -X DELETE 'https://cp-console.apps.mycluster.mydomain.fyre.ibm.com/idprovider/v3/auth/idsource/defaultSP' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"

The response resembles the following code:

{
    "status": "success",
    "message": "{defaultSP} is deleted"
}

The error message resembles the following code:

400 "error": "Insufficient user permission for role : rolename"
404 "error": "Document not found"
500 "error": "Other errors"
202 OK Response

Getting the host details

  1. Install OC (OpenShift Container) client and connect to the OCP (OpenShift Container Platform) cluster. For more information, see Getting started with the OpenShift CLI.

  2. Get the hostname from the route available in ibm-common-service namespace or where the foundational services is installed.

oc get route -n ibm-common-services cp-console -o jsonpath='{.spec.host}' && echo

The sample output:

cp-console.apps.mycluster.mydomain.com

Different schema elements for IdP V2

The values of the saml_ldap elements are case-sensitive.

For example,

"scim_attribute_mappings": {
    "user": {
    "principalName": “values_to_be_mapped”,
        "givenName": "values_to_be_mapped",
        "middleName": "values_to_be_mapped",
        "familyName": "values_to_be_mapped",
        "formatted": "values_to_be_mapped"
        },
        "group": {
            "principalName": "values_to_be_mapped",
            "created": "values_to_be_mapped",
            "lastModified": "values_to_be_mapped"
            }
        }

Tested values for ISV SCIM:

"scim_attribute_mappings": {
    "user": {
        "principalName": "userName",
        "givenName": "name.givenName",
        "middleName": "name.middleName",
        "familyName": "name.familyName",
        "formatted": "name.formatted"
        },
        "group": {
            "principalName": "displayName",
            "created": "meta.created",
            "lastModified": "meta.lastModified"
            }
     }

"token_attribute_mappings": {
        "uid": "values_to_be_mapped",
        "first_name": "values_to_be_mapped",
        "last_name": "values_to_be_mapped",
        "groups": "values_to_be_mapped",
        "email": "values_to_be_mapped"
        }

The mapping is the IAM token claims. The mapping value is the identity provider (for example, ISV) user attribute name. If the names match, it is optional to list out the mapping, such as given_name, family_name, and email. The mapping shows what user attribute values to use when foundational services IAM generates ID token. The values are stored in the local database. IBM supports OIDC standard claims, such as given_name, family_name, email and sub, and additional claim groups in the mapping. You need to replace only the values_to_be_mapped based on the SAML configuration. The mapped values are case-sensitive.

Different schema elements for IdP V3

"token_attribute_mappings": {
        "groups": "values_to_be_mapped",
        "given_name": "values_to_be_mapped",
        "family_name": "values_to_be_mapped",
        "sub": "values_to_be_mapped",
        "email": "values_to_be_mapped"
        }

The mapped values are case-sensitive.

For SAML with SCIM dependency:

For example,

    "scim_config": {
      "scim_base_path": "https://bedrock-iam.verify.ibm.com/v2.0/",
      "grant_type": "client_credentials",
      "token_url": "https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token",
      "client_id": "Your_isv_client_id",
      "client_secret": "Your_isv_client_secret",
      "scim_attribute_mappings": {
        "user": {
          "principalName": "userName",
          "givenName": "name.givenName",
          "middleName": "name.middleName",
          "familyName": "name.familyName",
          "formatted": "name.formatted"
        },
        "group": {
          "principalName": "displayName",
          "created": "meta.created",
          "lastModified": "meta.lastModified"
        }
      }
    }

For SAML with LDAP dependency:

For example,

"ldap_config":
{
  "ldap_id": "existing-ldap-connection-name"
}