Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Client application configuration

Identity provider API

search

Identity provider API

These APIs allow the retrieval of identity-provider (IDP) configurations via a REST API.

Identity provider endpoints

All endpoints are protected with the API client credentials (either client secret basic or private key JWT, depending on the client authentication method). It requires an API client with the Config API scope.

Get a specific IDP

This returns the details of a specific identity provider.

  • Endpoint: /api/v1/configuration/idps/{idpId}/
  • Method: GET

Note

The / at the end is required.

Path parameters:

Param Required Description
idpId yes Unique identifier of the IDP.

Example request:

GET /api/v1/configuration/idps/customIdp/ HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "id": "customIdp",
   "name": "Custom Identity Provider",
   "type": "CUSTOM",
   "enabled": true,
   "default": true
}

Get all IDPs

This returns all configured identity providers.

  • Endpoint: /api/v1/configuration/idps
  • Method: GET

Example request:

GET /api/v1/configuration/idps HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "result": [
        {
            "id": "cimapi",
            "name": "cimapi",
            "type": "ONEGINI_API_ONE_STEP",
            "enabled": true,
            "default": false
        },
        {
            "id": "oneginiidp",
            "name": "oneginiidp",
            "type": "ONEGINI",
            "enabled": true,
            "default": false
        }
    ]
}

In the event of an error, one of the generic error codes are returned.

Create an IDP

This creates a new IDP.

  • Endpoint: /api/v1/configuration/idps
  • Method: POST

Supported Identity Provider types: TULIP, OAUTH, ID_BROKER

JSON body parameters:

Param IDP type Required Description
id all yes Unique identifier for an IDP
name all yes Unique name of an IDP
type all yes Identity provider type
Supported types: TULIP, OAUTH, ID_BROKER
enabled all no Specify whether an IDP is enabled
Default value: true
default all no Specify whether an IDP is default
Default value: false
issuer_uri TULIP yes URI of the issuer. This URI is used to read the OpenID Connect configuration.
client_id TULIP, OAUTH yes Client identifier.
client_secret TULIP, OAUTH depends Client secret
Required if client authentication method is client_secret_basic or client_secret_post
client_authentication_method TULIP, OAUTH no Client authentication method
Supported values: private_key_jwt, client_secret_basic, client_secret_post
Default value is private_key_jwt
scopes TULIP, OAUTH no Space-separated scopes.
end_session_enabled TULIP no Specify whether end session integration is enabled for this IDP
Default value: false
integrations TULIP no List of enabled integrations
Supported values: APP_TO_WEB, UDH_API
tulip_api_client_id TULIP depends Client identifier for Tulip API calls
Required when APP_TO_WEB or UDH_API integration is enabled
tulip_api_client_secret TULIP depends Client secret for Tulip API calls
Required when APP_TO_WEB or UDH_API integration is enabled and authentication method is client_secret_basic or client_secret_post
tulip_api_base_url TULIP depends This is the base URL of the Tulip brand without a trailing slash. UDH and app-to-web use this as a base for their URLs.
Required when APP_TO_WEB or UDH_API integration is enabled.
tulip_api_access_scope TULIP depends Space-separated scopes for the required Tulip segments, such as iwelcome:segment:example
Required when APP_TO_WEB or UDH_API integration is enabled
tulip_api_used_auth_methods TULIP no List of auth methods for the app-to-web integration with Tulip, such as ["SMS", "another"]
Used when APP_TO_WEB integration is enabled
udh_with_origin_client TULIP no If the persona selection in Tulip is based on a user/client combination (and not session), this feature needs to be enabled to send the origin web client or saml sp to Tulip.
authorization_url OAUTH yes Oauth authorization endpoint
token_url OAUTH yes Oauth token endpoint
profile_url OAUTH yes OpenID Connect UserInfo endpoint
user_info_enabled OAUTH no Specify whether the person API is enabled for this IDP
Default value: false
user_info_endpoint OAUTH depends Identity source URL. The URL of the API that provides the user identity. Use the {userId} placeholder for the userId path param, such as https://host/api/persons/{userId}/profile
Required when the user_info_enabled is true
user_info_username OAUTH depends Identity source username
Required when user_info_enabled is true.
user_info_password OAUTH depends Identity source password
Required when user_info_enabled is true.

Example TULIP type request:

POST /api/v1/configuration/idps
Host: onegini.example.com
Content-Type: application/json
{
   "id": "tulip-idp",
   "name": "Tulip Idp",
   "type": "TULIP",
   "client_id": "oauth2CustomerApp",
   "issuer_uri": "https://tulip.onewelcome.com/segment/login/oauth2/v1",
   "end_session_enabled": true,
   "scopes": "openid",
   "integrations": [
      "APP_TO_WEB",
      "UDH_API"
   ],
   "tulip_api_client_id": "accessIntegration",
   "tulip_api_base_url": "https://tulip-api.onewelcome.com/segment",
   "tulip_api_access_scope": "iwelcome:segment:example",
   "tulip_api_used_auth_methods": [
        "SMS",
        "another"
    ]
}

Example OAUTH type request:

    POST /api/v1/configuration/idps
    Host: onegini.example.com
    Content-Type: application/json
    {
    "type": "OAUTH",
    "id": "oauth-idp",
    "name": "OAuth Identity Provider",
    "client_id": "oauth2CustomerApp",
    "authorization_url": "https://example.com/oauth/v1/authorize",
    "token_url": "https://example.com/oauth/v1/token",
    "profile_url": "https://example.com/oauth/v1/userinfo",
    "scopes": "openid profile email"
    }

Example ID_BROKER type request:

    POST /api/v1/configuration/idps
    Host: onegini.example.com
    Content-Type: application/json
    {
    "type": "ID_BROKER",
    "id": "id-broker",
    "name": "ID Broker Identity Provider"
    }

Example success response:

    HTTP/1.1 201 CREATED
    Content-Type: application/json;charset=UTF-8
    Cache-Control: no-store
    Pragma: no-cache
    Location: /api/v1/configuration/idps/tulip-insurcar

The success response body is empty.

Delete IDP

This removes an identity provider.

  • Endpoint: /api/v1/configuration/idps/{id}
  • Method: DELETE

Path parameters:

Param Required Description
id yes Unique identifier for an IDP

Example request:

DELETE /api/v1/configuration/idps/oneginiidp HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

Error codes

One of the following responses is returned, containing a JSON object with an error code, a message, and details about the error.

HTTP status Error code Message
400 invalid_request One or more parameters is missing or incorrect. The details contain the missing or incorrect parameters.
401 unauthorized Provide valid credentials to get access to the API.
403 forbidden Operation is not allowed for the current user.
404 not_found Identity provider for given ID cannot be found

On this page