Open topic with navigation

Kony Fabric console User Guide: Identity > Configure the Identity Service > Kony Custom Identity Service > Custom Identity Agreement

Kony Custom Identity Service

Kony Fabric identity service supports federating authentication and authorization with external identity services over standard protocols.

Note: A Federated Identity is an electronic identity that maps attributes of a person across multiple identity services.

To authenticate users before accessing Kony Fabric services, Kony Fabric supports various types of identity services, such as Microsoft Active Directory, Salesforce, SAML, SAP, Kony SAP Gateway and User Repository. Each of these identity services agrees on a specific input and output format for authentication. The input and output formats differ based on back-end providers.

With Kony Fabric's custom authentication, a user can log in to any back-end provider's custom protocols by providing any parameters that the back-end provider supports, such as a userid and password, or a secret key.

Important:  Custom identity service APIs should support application/ x-www-form-urlencoded.

For example, when you send user input (username and password) to an auth service, the input is sent as JSON input, shown below:
{ "userid" : "user@user.com",
"password" : "password" }

For a custom identity service, user inputs are sent as / x-www-form-urlencoded.

Important:  SDK support for custom auth provider is available from Kony Fabric 6.0.4 onwards.

You can configure a custom auth service by pointing to an end point that implements the custom identity protocol. A custom identity protocol can be implemented by using Kony Fabric integration service or by an external service.

Note:  A custom identity protocol is implemented by a third-party back-end provider, or configured as an integration service by using the Kony Fabric Console.

How to Configure Kony Custom Identity Provider

To configure Kony custom identity provider, follow these steps:

  1. Under the Identity service designer page, type a name for the service in the Enter Service Name text box.
  2. From the Type of Identity list, select Custom.

    Note:  Fields marked with an asterisk are required.

  3. In the Custom Identity Service Endpoint text box, choose one option:
    • Enter a custom identity endpoint implemented by an external service. The endpoint should be in compliant with the custom identity provider API contract. The custom identity protocol implemented by an external service is the direct URL of a back-end provider. For more details, see the Custom identity protocol by an external service
      topic.
    • Enter a custom identity endpoint configured as an integration service.  A custom endpoint URL (Kony Fabric's custom identity protocol) is available in the App Service Document after you publish an app. The app should contain an integration service with login and logout operations. For more details, refer Configuring a Custom Identity service by using an Integration service.

      Important:   A custom endpoint URL is available from a successfully published app. You must use a custom endpoint URL for a custom identity service within the same app.

  4. The Enable MFA check box enables you to configure MFA for the Custom Identity Service. However, when configured, whether MFA is used for a particular identity service call is determined at runtime based on the response for the login service.
    This check box is selected by default. This helps you in the Test Login flow in design time environment to test the status of the short-lived known_user token (whether it is issued or not).
    You can uncheck it if MFA is not required.
  5. In MFA Validate Endpoint, type the URL to which the Identity Service should send the request to validate the MFA key and get the authenticated token. This feature is linked to the Enable MFA check box. If the Enable MFA check box is selected, this field is mandatory. If the Enable MFA check box is unchecked, this field is disabled.
    If you give the MFA endpoint details, this adapter will act as a Multi Factor Authentication (MFA) adapter in design time environment. For more information, refer Custom Identity MFA Flow.
  6. In the Provider Settings (Optional) section, click the Add button.

    Note:  When you enter text in the Enter Parameter Key text box, a new row is automatically added below the first row.
    You can also delete an entry by clicking the Delete button that appears next to each entry.

  7. In the Enter Parameter Key text box, enter the parameter you want to configure as an additional attribute. For example, <Backend-config-key>.
  8. To move the cursor to the next text box, press the Tab key or click in the text box. In the Enter Parameter Value text box, enter the value for the parameter. For example, <backend-config-key-value>.

    Important:     You can add any key-value pairs. When an identity service makes a login call to a back-end provider, the identity service sends key-value pairs along with the call request. Confidential key-value pairs can be added under the Provider Settings (Optional) section instead of by adding these details in a client app.

  9. In the Provider Headers (Optional) section, enter the headers from the login request to be stamped on the requests made to the endpoint.
  10. In the Advanced section, you can do the following:
    • In User Attributes, type the URL that you want to invoke after an identity session is created to get the custom user attributes created for the user who is trying to login to the client app. The custom user attributes can be any information related to the user like DoB, Gender, and more. This field is optional.
      If you provide the URL, any additional user attributes that were configured will be appended to the respective section in the login response after a successful login
    • In Security Attributes, type the URL that you want to invoke after an identity session is created to get the custom security attributes created for the user who Is trying to login to the client app. The security attributes are stored in Kony Fabric and not shared with the users. This field is optional.
      Any secure info like credit card number, SSN which need not be sent to client app, but is required for backend processing, must be sent as security attribute.
    • In Post Authentication URL, enter the URL to be invoked after an identity session is created. After this URL is invoked, the Identity response is returned to the Client.
    • Now you can enable or disable the integrity check for an identity service at the provider level. If the integrity is disabled at the provider level, then the provider is meant for server-to-server communication only. To disable the integrity check, In Advanced, select the Restrict to Fabric Server to Server Authentication check box. This setting blocks a traditional client app from using an identity service. It will only allow the identity service to be used from a Kony Fabric Server to authenticate and invoke services.
    • Concurrent User Logins: Select one of the following three options to configure concurrent user login sessions. For more information, refer to Concurrent User Logins.
      • Allow concurrent user sessions (no restrictions): When this option is selected, an app user with unique credentials is allowed to have multiple apps from different instances.
      • Allow only one active user session per app: Logging into simultaneous instances of the same app is not supported. When this option is selected, an app user can log in to only one instance of client apps linked to a specific Fabric app which has the identity service linked.
      • Allow only one active user session across all apps: Logging to simultaneous instances of the same app or across apps is not supported. When this option is selected, a unique app user can log in to only one instance of client apps linked to all Fabric apps using the identity service.

        Important: Apps enabled for SSO will not work if the option is selected, Allow only one active user session across all apps.

  11. After entering the above details, click the Test Login button to verify the credentials. The Test Login dialog appears.

    1. Enter the required details in headers and body for custom identity provider.

      The entries for Header and Body are auto-inserted into the login request. You can delete an entry by clicking the Delete button next to the entry.

    2. Click Sign In.

      The test results are displayed in the Identity Response dialog.

  12. Click SAVE to save the service. The system displays the Identity page. The custom identity service is configured.

    Note: You can view the service in the Data Panel feature of Kony Visualizer. By using the Data Panel, you can link back-end data services to your application UI elements seamlessly with low-code to no code. For more information on Data Panel, click here.

Custom Identity Agreement

The following APIs must be implemented by a custom identity hosting service as the endpoint_url configuration parameter:

Login API for a Custom Identity Service

The Login API authenticates user access to a custom identity provider. This API should comply with the custom identity protocol mentioned in this section.

Method

POST

Headers

X-Kony-RequestId: <Request Id>

Content-Type: application/formurl-encoded only

Accept: application/json or application/xml

Sample Request Body:

 {
    “<custom_key1>” : <custom_value1>,
   “<custom_key2>” : <custom_value2>,
    …
}

Details:

Sample Success Response if MFA is enabled

The response contains is_mfa_enabled and mfa_meta fields if the back-end supports MFA. The user and security attributes are displayed after MFA validation. Following is the sample success response:

HTTP 200 OK

{
...
"is_mfa_enabled":true,
"mfa_meta":{"otp":2},
...
}

Important: The "mfa_meta" field varies depending on the type of MFA set in the backend server. The login service uses it to indicate to client app the type of MFA to be used like OTP, Security questions or even to invoke the security questions. This meta is available for client app to help the client app logic determine the actual mechanism of getting the MFA delivered.

Sample Success Response if MFA not enabled:

If an end user does not require MFA or has not enabled it, then the is_mfa_enabled field is set to false and the user profile information and claims token are available in the response. There will be no further MFA validation in the current service call instance. Following is the sample success response:

HTTP 200 OK

 
{
"is_mfa_enabled":false,

“security_attributes” : {
“session_token”: “<session_token>”,
“session_ttl”: <>, /* -1 : if ttl is not available.  
Else TTL in msecs */
“<optional key1>”: “<value1>”,  /* ex: refresh_token
“<optional key2>”: “<value2>”,
    },
   “user_attributes”:  
{
"user_id” : “<userID_number>", /* federation ID of the user from custom identity service
“<attr1>” : “<value1>”, /*ex: “first_name”: “<firstname>” */
“<attr2>” : “<value2>”, /*ex: “user_id”: “<user_id>” */
“<attr3>” : “<value3>”, /*ex: “role”: “<role>” */
   }
}

Note: If "is_mfa_enabled" field is not there in the server response, then the backend server does not support MFA.

Important: The user_id is a mandatory field in the log-in response.

Sample Success Response with httpStatusCode:

HTTP 200 OK

 {
“security_attributes” :

{ “session_token”: “<session_token>”, “session_ttl”: <>, /* -1 : if ttl is not available. Else TTL in msecs */ “<optional key1>”: “<value1>”, /* ex: refresh_token “<optional key2>”: “<value2>”, }
,
“user_attributes”:

{ "user_id” : “<userID_number>", /* federation ID of the user from custom identity service “<attr1>” : “<value1>”, /*ex: “first_name”: “<firstname>” */ “<attr2>” : “<value2>”, /*ex: “user_id”: “<user_id>” */ “<attr3>” : “<value3>”, /*ex: “role”: “<role>” */ }
,
"httpStatusCode" : 200 /* please note this is an integer. if this is not 200 custom login will fail */
}

Possible Failure Responses 

Failure response when Custom identity protocol is configured as an integration service
{
    "details": {
        "message": "Middleware Service returned a HTTP Response Status [401], OpStatus [8009], Error Message [Request unsuccessful for service login, server responded with status code 401]",
        "errcode": 123,
        "errmsg": "backendErrorMessage"
    },
    "httpstatus": "Unauthorized",
    "requestid": "b5bb895b-7cc7-40db-8cfc-a2d69bfd31f9",
    "domain": "AUTH",
    "code": -14,
    "mfcode": "Auth-14",
    "message": "Configured IdP Service Unavailable"
}

To map the backend_error_code and backend_error_message with the errcode and errmsg of the Identity Service, the two values should be mapped to the integration service response output.

After mapping, the Integration Service response for the failed authentications is displayed as below:

 {
    "backend_error_message": "backendErrorMessage",
    "opstatus": 8009,
    "errmsg": "Request unsuccessful for service login, server responded with status code 401",
    "backend_error_code": "123",
    "httpStatusCode": 401
}

The Identity service extracts backend_error_code and backend_error_message from the integration response and maps them to the errcode and errmsg and sends the response.

 {
    "details": {
        "message": "Middleware Service returned a HTTP Response Status [401], OpStatus [8009], Error Message [Request unsuccessful for service login, server responded with status code 401]",
        "errcode": 123,
        "errmsg": "backendErrorMessage"
    },

Logout API for a Custom Identity Service

The Logout API clears the session of a logged-in user. The Logout API is optional for a custom identity service. You need to configure the logout API only if a logged-in user is associated with a session. You can configure the logout API in the Kony Fabric Console.

Method

POST

Headers

X-Kony-RequestId: <Request Id>

Content-Type: application/formurl-encoded only

Accept: application/json or application/xml

Sample Body Request: 

 {
   “session_token” : “<Session Token>”
}

Details:

session_token (optional)

Session Token of the user session in custom identity service

Sample Success Response:

Sample Failure Response: 

 {
 “domain” : “custom”,
 “code” : <error code>,
 “message” : <Error Message>,
 “details” : {
 “message” : <Detailed Error Message>,
    },
  “requestid” : <Request Id>,
}

MFA API

If MFA is enabled, the client app should have the necessary logic to validate the MFA with any configured endpoint(s) such as an integration service to generate and validate OTP, or validate security questions entered in client app. Post the validation, the integration service should return an MFA key (mfa_key) to the client app, which should be passed using the Fabric SDK API to MFA validation endpoint along with known_user token. The endpoint should be configured to confirm the authenticity of the mfa_key and accordingly send a successful response or failure. This 2 step process is to ensure that the backend generating MFA is not implicitly trusted by identity, but validates the mfa_key, before generating an authenticated session for the same. The MFA validation endpoint is invoked with the following parameters.

Sample Request Body 

{
    “<mfa_key>” : <mfa key>,
    …
}

Note: To know more about other parameters that are added by SDK, refer to the SDK document.

Sample Success Response

HTTP 200 OK

{
“security_attributes” : {},
“user_attributes”:  
{
/* Fetched from Custom Identity Endpoint*/
"user_id” : “<userID_number>", /* federation ID of the user from custom identity service
“<attr1>” : “<value1>”, /*ex: “first_name”: “<firstname>” */
“<attr2>” : “<value2>”, /*ex: “user_id”: “<user_id>” */
“<attr3>” : “<value3>”, /*ex: “role”: “<role>” */

/*Fetched from User Attributes Endpoint*/
“<attr4>” : “<value4>”, /*ex: “mobile_number”: “<mobile_number>” */
“<attr5>” : “<value5>”, /*ex: “department”: “<department>” */
“<attr6>” : “<value6>”, /*ex: “job_title”: “<job_title>”  */

}
}

User Attributes Endpoint API

The User Attributes Endpoint API retrieves additional user profile data which will passthrough integration service.

Method

GET

Headers

X-Kony-RequestId: <Request Id>

X-Kony-Authorization: <claims _token>

Content-Type: application/formurl-encoded only

Accept: application/json

Sample Success Response:

HTTP 200 OK

“user_attributes”:  
{

/* Fetched from Custom Identity Endpoint*/
"content_type": "application/json",
"user_id” : “<userID_number>", /* federation ID of the user from custom identity service
“<attr1>” : “<value1>”, /*ex: “first_name”: “<firstname>” */
“<attr2>” : “<value2>”, /*ex: “user_id”: “<user_id>” */
“<attr3>” : “<value3>”, /*ex: “role”: “<role>” */ 

/*Fetched from User Attributes Endpoint*/
“<attr4>” : “<value4>”, /*ex: “mobile_number”: “<mobile_number>” */
“<attr5>” : “<value5>”, /*ex: “department”: “<department>” */
“<attr6>” : “<value6>”, /*ex: “job_title”: “<job_title>”  */
…

}

Sample for Failure Response:

If invocation of optional User Attributes Endpoint fails and returns a successful response, then the response will have the following failure information:

HTTP 200 :

“user_attributes”:  
{

"content_type": "application/json",
"user_id” : “<userID_number>", /* federation ID of the user from custom identity service
“<attr1>” : “<value1>”, /*ex: “first_name”: “<firstname>” */
“<attr2>” : “<value2>”, /*ex: “user_id”: “<user_id>” */
“<attr3>” : “<value3>”, /*ex: “httpStatusCode”: “<200>” */
…

“<httpStatusCode >” : “<200>”, /*ex: “httpStatusCode”: “<200>” */
“<opstatus>” : “<value4>”, /*ex: “opstatus”: “<integer value>” */
“<errmsg>” : “<value5>”, /*ex: “errmsg”: “<error details>” */ 

}

Security Attributes Endpoint API

The Security Attributes Endpoint API retrieves additional security attributes data which will passthrough integration service. These are server only attributes and are accessible from the custom code in server (pre/post processors).

Method

GET

Headers

X-Kony-RequestId: <Request Id>

X-Kony-Authorization: <claims _token>

Content-Type: application/formurl-encoded only

Accept: application/json

Sample Success Response:

HTTP 200 OK

“user_attributes”:  
{
"content_type": "application/json",
"user_id” : “<userID_number>", /* federation ID of the user from custom identity service
“<attr1>” : “<value1>”, /*ex: “session_token”: “<session_token>” */
“<attr2>” : “<value2>”, /*ex: “refresh_token”: “<refresh_token>” */
“<attr3>” : “<value3>”, /*ex: “_provider_token”: “<_provider_token>”
 */
…

“<attr4>” : “<value4>”, /*ex: “session_auto_extend”: “<session_auto_extend
>” */
“<attr5>” : “<value5>”, /*ex: “session_idle_timeout”: “<session_idle_timeout>” */ 
…
}

Sample Failure Response

If invocation of optional Security Attributes Endpoint fails and returns a successful response, then the response will have the following failure information:

HTTP 200:

“user_attributes”:  
{
“<attr1>” : “<value1>”, /*ex: “session_token”: “<session_token>” */
“<attr2>” : “<value2>”, /*ex: “refresh_token”: “<refresh_token>” */
“<attr3>” : “<value3>”, /*ex: “provider_token”:“<provider_token>”*/
…

“<opstatus>” : “<value4>”, /*ex: “opstatus”: “<integer value>” */
“<httpStatusCode >” : “<httpStatusCode >”, /*ex: “httpStatusCode”: “<200>” */
“<errmsg>” : “<value5>”, /*ex: “errmsg”: “<error details>” */ 

}

Custom Identity MFA Flow

Initial Call Process

When a user signs in to the application for the first time, the following calls occur among the app, Identity service, and server:

Subsequent Call Process

On subsequent logins, the following calls occur among the app, Identity service, and server:

Copyright © 2020 Kony, Inc. All rights reserved.

Open topic with navigation