Identity Providers

These APIs allow the retrieval of configuration of identity-providers via a REST API.

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 scope Config API.

Get a specific Identity Provider

This returns the details of a specific Identity Provider.

• Endpoint: /api/v1/configuration/idps/{idpId}/
• Method: GET
• Please note that / at the end is required

Path parameters:

Param	Required	Description
idpId	yes	Unique identifier of the Identity Provider.

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 identity providers

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 will be returned.

Create Identity Provider

This creates an Identity Provider from scratch

• 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 Identity Provider.
name	all	yes	Unique name of an Identity Provider.
type	all	yes	Identity Provider type. Supported types: TULIP, OAUTH.
enabled	all	no	Specify whether an Identity Provider is enabled. Default value: true.
default	all	no	Specify whether an Identity Provider is default. Default value: false.
issuer_uri	TULIP	yes	Uri of the issuer. This URI will be 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 Identity Provider. 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 should be the base url of the Tulip brand without a trailing slash. UDH and App To Web will 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 e.g. 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 e.g. ["SMS", "another"]. Used when APP_TO_WEB integration is enabled.
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 CIM's Person API is enabled for this Identity Provider. Default value: false.
user_info_endpoint	OAUTH	depends	Identity source URL. The URL of API that provides user's identity. Use {userId} placeholder for userId path param. e.g. https://host/api/persons/{userId}/profile Required when 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 Identity Provider

This removes an Identity Provider.

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

Path parameters:

Param	Required	Description
id	yes	Unique identifier for an Identity Provider.

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 will be 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