Enable and Manage SSO Configuration APIs¶

To execute and get results for managing an account’s SSO configurations with the following APIs:

Note

The APIs support SAML, WSFED, and OpenID Connect protocols.

Fetch the SSO Meta API¶

If SSO is enabled, this API returns the existing SSO configuration along with the URLs. Otherwise, it returns only the URLs. This document covers both the scenarios.

Method	GET
Endpoint	`https://{{host}}/api/public/bot/{{BotID}}/ssoconfig`
Content Type	`application/json`
Authorization	`auth: {{JWT}}` See How to generate the JWT Token.
API Scope	Bot Builder: Not Applicable Admin Console: User Management > SSO Configuration

Query Parameters¶

PARAMETER	DESCRIPTION	REQUIRED/OPTIONAL
host	The environment URL. For example, https://bots.kore.ai	Required
BotId	The Bot ID or Stream ID can be accessed under General Settings on the Bot Builder.	Required
SSOProtocol	The value for SSO protocol.	Required

Sample Request¶

curl --location --request GET \
'https://{{host}}/api/public/ssoconfig?SSOProtocol=saml' \
--header 'auth: {jwt-token}' \
--header 'bot-language: {language-code}' \
--header 'Content-Type: application/json' \
--data ''

Body Parameters¶

If SSO is enabled

In this case, the API provides the following meta of the configurations.

PARAMETER	DATA TYPE	DESCRIPTION	REQUIRED/OPTIONAL
ACS IDP URL	String	ACS URL for IDP Initiated SAML Flow.	Required
ACS SP CallBack URL	String	ACS URL for SP Initiated SAML Flow.	Required
Method	String	The method used for the SSO flow. For example, SAML.	Required
ssoProvider	String	The options include: Okta Others OneLogin Bitium	Required
modifiedDate	Date	The date when the SSO configuration was modified in `YYYY-MM-DD` format, and Time in `HH:MM:SS` format.	Required
modifiedBy	Array of String data type.	This parameter supports an array of objects. Each object in the array has the parameters that are listed below: userId: The admin user’s ID. firstName: The admin user’s first name. lastName: The admin user’s last name.	Required
cert	String	The SSO certificate. Note: This field is an array. The Maximum number of values supported is two.	Required
entryPoint	String	The URL of the SSO entry point.	Required
Issuer	String	The URL of the SSO issuer.	Required
samlAttributeMapping	Array of Objects of String data type.	This parameter supports an array of objects. Each object in the array has the mandatory parameters listed below: samlAttributeName: The SAML attribute name of String data type used for SSO. samlAttributeValue: The SAML attribute value of String data type used for SSO. attributeType: The SAML attribute type which is either Role or Group to which an attribute is mapped. koreAttribute: The Role ID or Group ID to which the SAML attribute should be mapped.	Required

If SSO is Disabled

In this case, the API provides the following meta required to enable the app at the identity provider application.

PARAMETER	DATA TYPE	DESCRIPTION	REQUIRED/OPTIONAL
ACS IDP URL	String	ACS URL for IDP Initiated SAML Flow.	Required
ACS SP CallBack URL	String	ACS URL for SP Initiated SAML Flow.	Required

Sample Response¶

If SSO is enabled

{
   "ACS_IDP_URL": "https://xxx.kore.ai/api/sso/login/callback?c=e-7dxxxxxcdxxxxxxcxxxxxxxxxc51xxxxxxxxxx21xxxxxxxxxxxxxxxxxxxxxxx4&redirect_url=httpsxxxxxxxxFsit-xo.kore.axxxxbotbuilderxxxx3Fquery%xx1",
   "ACS_SP_CallBack_URL": "https://idpxxxy-dxx.kore.com/authorize/callback",
   "ssoConfig": {
       "method": "saml",
       "allusers": false,
       "ssoProvider": "okta",
       "modifiedDate": "2024-07-23T07:12:26.549Z",
       "modifiedBy": {
           "userId": "u-94xxxxx8-bxxb-5xx6-9xx0-06xxxxxxxxxf",
           "firstName": "pxxxxxn",
           "lastName": "`bxxxxx"
       },
       "config": {
           "cert": [
               "{certificate ID}"
           ],
           "entryPoint": "https://trial-6xxxxx1.okta.com/app/trial-61xxxxx_kxxe_1/exxxxxxxxxxxxxxxx697/sso/saml",
           "issuer": "http://www.okta.com/exxxxxxxxxxxxxxxxxx7"
       },
       "samlAttributeMapping": {
           "fullSynchronization": "enabled",
           "status": "active",
           "attributeMapping": [
               {
                   "samlAttributeName": "role",
                   "samlAttributeValue": "role1",
                   "attributeType": "Role",
                   "koreAttribute": "6xxxxxxxxxxxxxxxxxxxxxeb"
               }
           ]
       }
   }
}

If SSO is disabled

{
   "ACS_IDP_URL": "https://xxx.kore.ai/api/sso/login/callback?c=e-7dxxxxxcdxxxxxxcxxxxxxxxxc51xxxxxxxxxx21xxxxxxxxxxxxxxxxxxxxxxx4&redirect_url=httpsxxxxxxxxFsit-xo.kore.axxxxbotbuilderxxxx3Fquery%xx1",
   "ACS_SP_CallBack_URL": "https://idpxxxy-dxx.kore.com/authorize/callback"
}

Enable SSO API¶

This API enables the SSO configuration for an account.

Method	POST
Endpoint	`https://{{host}}/api/public/bot/{{BotID}}/ssoconfig`
Content Type	`application/json`
Authorization	`auth: {{JWT}}` See How to generate the JWT Token.
API Scope	Bot Builder: Not Applicable Admin Console: User Management > SSO Configuration

Path Parameters¶

PARAMETER	DESCRIPTION	REQUIRED/OPTIONAL
host	The environment URL. For example, https://bots.kore.ai	Required
BotId	The Bot ID or Stream ID can be accessed under General Settings on the Bot Builder.	Required

Sample Request¶

curl --location --request POST \
'https://{{host}}/api/public/ssoconfig' \
     --header 'auth: {jwt-token}' \
     --header 'bot-language: {language-code}' \
     --header 'Content-Type: application/json' \
--data '{
    "SSO_Authentication": "enable",
    "SSOProtocol": "saml",
    "SAML_IdentityProvider": "onelogin",
    "SingleSignOnURL": "https://prxxxxng1.onelogin.com/trust/saml2/http-post/sso/3xxxxxe0-8xx6-4xx8-9xx1-dxxxxxx7dxxe",
    "IssuerURL": "https://app.onelogin.com/saml/metadata/3xxxxxe0-8xx6-4xx8-9xx1-d1xxxx07dxxe",
    "Certificate": [
        "{certificate ID}"
    ],
    "SAMLAttributeMapping": true,
    "SyncBehaviour": "Synchronize_UpdateExisting",
    "AttributeMapping": [
        {
            "SAMLAttribute_Name": "role",
            "SAMLAttribute_Value": "role1",
            "Attribute_Type": "Role",
            "Kore_Attribute": "667xxxxxxxxxxxxxxxxxxxxb"
        }
    ]
}'

Body Parameters¶

PARAMETER	DATA TYPE	DESCRIPTION	REQUIRED/OPTIONAL
SSO Authentication	String	This parameter enables the overall configuration.	Required
SSO Protocol	String	This parameter indicates the SSO protocol the admin wants to enable for the account.	Required
SAML Identity Provider	String	This parameter defines the SAML Identity provider the admin is using to enable the SSO.	Required
Single SignOn URL	String	The SSO URL for the account.	Required
Issuer URL	Date	The URL of the SSO issuer.	Required
certificate	String	The SSO certificate. Note: This field is an array. The Maximum number of values supported is two.	Required
SAML Attribute Mapping	Boolean	If enabled (true), SAML attribute mapping is done based on the sync behavior.	Optional. If the parameter is not defined in the request body, the default value is Disabled (False).
Sync Behaviour	String	Includes one of the following values: Synchronize_UpdateExisting: Synchronize by updating the existing SSO configuration. AddNew_RetainExisting: Add a new SSO configuration by retaining the existing values.	Required if the SAMLAttributeMapping parameter is enabled.
Attribute Mapping	Array of Objects of String data type.	This parameter supports an array of objects. Each object in the array has the mandatory parameters listed below: samlAttributeName: The SAML attribute name of String data type used for SSO. samlAttributeValue: The SAML attribute value of String data type used for SSO. attributeType: The SAML attribute type which is either Role or Group to which an attribute is mapped. koreAttribute: The Role ID or Group ID to which the SAML attribute should be mapped.	Required

Sample Response¶

{
   "config": {
       "cert": [
           "{certificate ID}"
       ],
       "entryPoint": "https://trial-6xxxxx1.okta.com/app/trial-6xxxxx1_kore_1/exxxxxxxxxxxxxxxxx97/sso/saml",
       "issuer": "http://www.okta.com/exxxxxxxxxxxxxxxxx97"
   },
   "method": "saml",
   "providername": "okta",
   "allusers": false,
   "modifiedBy": "u-9xxxxxx8-bxxb-5xx6-9xx0-06xxxxxxxxxf",
   "samlAttributeMapping": {
       "fullSynchronization": "enabled",
       "status": "active",
       "attributeMapping": [
           {
               "samlAttributeName": "role",
               "samlAttributeValue": "role1",
               "attributeType": "Role",
               "koreAttribute": "6xxxxxxxxxxxxxxxxxxxxeeb"
           }
       ]
   },
   "name": "joxx.xx@kore.com_saml",
   "ssoProvider": "okta",
   "ACS_IDP_URL": "https://xxxx.kore.ai/api/sso/login/callback?c=e-7dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4&redirect_url=httpsxxxxxxx2Fxxxx.kore.ai%xxxbotbuilder%xx%3xquery%3x1",
   "ACS_SP_CallBack_URL": "https://xxxxx-dev.kore.com/authorize/callback",
  }

Disable SSO API¶

This API disables the SSO configuration for an account.

Method	DELETE
Endpoint	`https://{host}/API/public/ssoconfig`
Content Type	`application/json`
Authorization	`auth: {{JWT}}` See How to generate the JWT Token.
API Scope	Bot Builder: Not Applicable Admin Console: User Management > SSO Configuration

Path Parameters¶

PARAMETER	DESCRIPTION	REQUIRED/OPTIONAL
host	The environment URL. For example, https://bots.kore.ai	Required

Sample Request¶

curl --location --request DELETE 'https://{{host}}/api/public/ssoconfig' \
     --header 'auth: {jwt-token}' \
     --header 'bot-language: {language-code}' \
     --header 'Content-Type: application/json' \
--data ''

Body Parameters¶

No body parameters.

Sample Response¶

{
   "message": "SSO Configuration disabled"
}

Update SSO API¶

This API updates the SSO configuration for an account.

Method	POST
Endpoint	`https://{host}/API/public/ssoconfig`
Content Type	`application/json`
Authorization	`auth: {{JWT}}` See How to generate the JWT Token.
API Scope	Bot Builder: Not Applicable Admin Console: User Management > SSO Configuration

Path Parameters¶

PARAMETER	DESCRIPTION	REQUIRED/OPTIONAL
host	The environment URL. For example, https://bots.kore.ai	Required

Sample Request¶

curl --location 'https://{{host}}/api/public/ssoconfig' \
--header 'auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6ImNzLTVjNDkzYmY3LTYxYWMtNWFlZC1hMTMzLTQ0ZGE3MmU0MmNlYyJ9.4XiqSkquaGSbmmW9SK0TY1wS1E-35gHvi6ZsQYt2Umc' \
--header 'Content-Type: application/json' \
--data '{
   "SSO_Authentication":"enable",
   "SSOProtocol": "saml",
   "SAML_IdentityProvider": "okta",
   "SingleSignOnURL": "https://trial-6124441.okta.com/app/trial-6124441_kore_1/exkgn9lkzgRaNi5dS697/sso/saml",
   "IssuerURL": "http://www.okta.com/exkgn9lkzgRaNi5dS697",
   "Certificate": ["{{certificate ID}}"],
    "SAMLAttributeMapping": true,
   "SyncBehaviour": "Synchronize_UpdateExisting",
   "AttributeMapping": [
       {
           "SAMLAttribute_Name": "role",
           "SAMLAttribute_Value": "role1",
           "Attribute_Type": "Role",
           "Kore_Attribute": "667d254fad30fa11a6f3eeeb"
       }
   ]
}'

Body Parameters¶

PARAMETER	DATA TYPE	DESCRIPTION	REQUIRED/OPTIONAL
SSO Authentication	String	When the value is set to “update,” this parameter updates the overall configuration.	Required
SSO Protocol	String	This parameter indicates the SSO protocol for the configuration update.	Required
SAML Identity Provider	String	This parameter defines the SAML Identity provider the admin is using to update the SSO.	Required
Single SignOn URL	String	The SSO URL for the account.	Required
Issuer URL	Date	The URL of the SSO issuer.	Required
certificate	String	The SSO certificate. Note: This field is an array. The Maximum number of values supported is two.	Required
SAML Attribute Mapping	Boolean	If enabled (true), SAML attribute mapping is done based on the sync behavior.	Optional. If the parameter is not defined in the request body, the default value is Disabled (False).
Sync Behaviour	String	Includes one of the following values: Synchronize_UpdateExisting: Synchronize by updating the existing SSO configuration. AddNew_RetainExisting: Add a new SSO configuration by retaining the existing values.	Required if the SAMLAttributeMapping parameter is enabled.
Attribute Mapping	Array of Objects of String data type.	This parameter supports an array of objects. Each object in the array has the mandatory parameters listed below: samlAttributeName: The SAML attribute name of String data type used for SSO. samlAttributeValue: The SAML attribute value of String data type used for SSO. attributeType: The SAML attribute type which is either Role or Group to which an attribute is mapped. koreAttribute: The Role ID or Group ID to which the SAML attribute should be mapped.	Required

Sample Response¶

{
   "method": "saml",
   "name": "joxxx.xx@kore.com_saml",
   "allusers": false,
   "ssoProvider": "okta",
   "modifiedDate": "2024-07-23T11:21:50.287Z",
   "modifiedBy": "u-9xxxxxx8-bxxb-5xx6-9xx0-0xxxxxxxxxxf",
   "config": {
       "cert": [
           "{cert ID}"
       ],
       "entryPoint": "https://trial-6xxxxx1.okta.com/app/trial-6xxxxx1_kore_1/exxxxxxxxxxxxxxxx697/sso/saml",
       "issuer": "http://www.okta.com/exxxxxxxxxxxxxxxxxx7"
   },
   "providername": "okta",
   "ACS_IDP_URL": "https://xxxxx.kore.ai/api/sso/login/callback?c=e-7dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx74&redirect_url=https%xxxxxxxxxx%xxxxxx.kore.ai%2xbotbuilder%2x%3Fquery%3x1",
   "ACS_SP_CallBack_URL": "https://ixxxxxy-dxv.kore.com/authorize/callback",
   "message": "SSO Configuration updated successfully"
}