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`, I`D_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

Identity provider API

Identity provider endpoints

Get a specific IDP

Get all IDPs

Create an IDP

Delete IDP

Error codes

On this page

Suggest A Change