SSO REST Web Service

The SSO REST Web Service is the official DirX Access interface that provides the following capabilities:

  • Authentication

  • Risk-based Authentication

    • The request is evaluated against configured RBA policies and can subsequently also suggest redirection to appropriate authentication method.

  • Authorization

    • The request is evaluated against corresponding authorization policies.

  • Single sign-on

    • The session identifier can be transported within the request to achieve the single sign-on.

  • Request/response injection

    • All corresponding request/response injection data are provided via the response.

  • Redirection mechanism

    • If subsequent processing of the request requires redirection to a known location (e.g., due to step-up authentication), this information is provided in the response.

Description

The SSO REST Web Service is described by the OpenAPI 3.0 document which can be found at {sso_rest_web_application_location}/openapi.json
or {sso_rest_web_application_location}/openapi.yaml.

Public OpenAPI tools are able to autogenerate documentation and clients for given document. The readers are recommended to use such tools (e.g., Swagger , or OpenAPI.Tools - an Open Source list of great tools for OpenAPI), mainly, for the generation of documentation file in a user-friendly format.

Deployment

The SSO REST Web Service functionality is provided based on the SSO REST web application. The application has to have its configuration and be deployed on the DirX Access Server. Multiple SSO REST applications can coexist on DirX Access Server, therefore configuration includes PortAssignment and context path.

The {sso_rest_web_application_location} of the SSO REST web application is constructed from the hostname of the DirX Access Server or Cluster, the port of the assigned PortAssignment configuration object and the web application context path.

The deployment can be done via Direct Application of System Actions and Configuration or SysActions REST Web Service.

Authorization

The authorization to the endpoint is supposed to be set to exclude. For more information, please see SSO REST Service.

Examples

Form Authentication

Request

POST {sso_rest_web_application_location}/PerformSso
{
    "ssoRequest": {
        "pepId": "{pep_id}",
        "authnMethodId": "{authn_method_id}"
    },
    "callbackHandler": [
        {
            "name": "{user_login_name}",
            "type": "net.atos.dirx.access.odata4.sso.NameCallback"
        },
        {
            "password": "{user_password}",
            "type": "net.atos.dirx.access.odata4.sso.PasswordCallback"
        }
    ]
}

For more information regarding request parameters, please see the OpenAPI 3.0 document.

Response

{
    "sessionId": "{session_id}",
    "cookies": [
        "DXASIDMYCOMPANY={session_cookie}; Domain={session_cookie_domain}; Path={session_cookie_path}"
    ],
    "redirectUri": "{redirection_target_uri}",
    "status": "OK",
    "isAuthorized": true,
    "inAttrs": [
        {
            "key": "E-Mail",
            "value": "{user_mail}"
        },
        {
            "key": "RoleAssignments",
            "value": "{user_roles}"
        }
    ],
    "inHeaders": [
        {
            "key": "DistinguishedName",
            "value": "{user_dn}"
        }
    ],
    "outHeaders": [
        {
            "key": "UIDs",
            "value": "{user_uid}"
        }
    ]
}

The successful authentication is represented by the sessionId and cookies parameter.

The request / response injection is represented by the inAttrs, inHeaders and outHeaders parameters. For more information, please see one of:

The redirection target is represented by the redirectUri parameter.

For more information regarding response parameters, please see the OpenAPI 3.0 document.

Composite Form OtpMail Authentication

In each composite authentication method, you typically need several steps / sso requests to successfully authenticate a user. The state among the sso requests are integrated by the authnSessionId parameter.

Request of the initial step

POST {sso_rest_web_application_location}/PerformSso
{
    "ssoRequest": {
        "pepId": "{pep_id}",
        "authnMethodId": "{authn_method_id_with_initial_step}"
    },
    "callbackHandler": []
}

In each composite authentication method, the initial step for clients can be set to provide the initial list of authentication methods for the first step. The initial step is optional. For more information, please see Administrative Tasks/Composite Authentication Methods.

Response of the initial step

{
    "type": "net.atos.dirx.access.odata4.sso.AuthnChallengeException",
    "clazz": "CompositeAuthnException",
    "data": {
        "status": "OK"
    },
    "challenge": {
        "@odata.type": "#net.atos.dirx.access.odata4.sso.CompositeChallenge",
        "type": "net.atos.dirx.access.odata4.sso.CompositeChallenge",
        "clazz": "CompositeAuthnException",
        "authnSessionId": "{authn_session_id}",
        "nextAuthnSteps": [
            {
                "authnMethodId": "{form_authentication_method_id}",
                "callbackTypes": [
                    "net.atos.dirx.access.odata4.sso.NameCallback",
                    "net.atos.dirx.access.odata4.sso.PasswordCallback"
                ]
            }
        ]
    }
}

The initial list of authentication methods is represented by the nextAuthnSteps parameter. There can be seen that the next authentication method is the {form_authentication_method_id}.

The state is represented by the authnSessionId parameter.

Request

POST {sso_rest_web_application_location}/PerformSso
{
    "ssoRequest": {
        "pepId": "{pep_id}",
        "authnMethodId": "{authn_method_id_with_initial_step}"
    },
    "callbackHandler": [
        {
            "name": "{user_login_name}",
            "type": "net.atos.dirx.access.odata4.sso.NameCallback"
        },
        {
            "password": "{user_password}",
            "type": "net.atos.dirx.access.odata4.sso.PasswordCallback"
        },
        {
            "authnSessionId": "{authn_session_id}",
            "type": "net.atos.dirx.access.odata4.sso.AuthnSessionIdCallback"
        }
    ]
}

In the request, there can be seen that the authnSessionId parameter was used for state integration.

Response

{
    "type": "net.atos.dirx.access.odata4.sso.AuthnChallengeException",
    "clazz": "CompositeAuthnException",
    "data": {
        "status": "OK"
    },
    "challenge": {
        "@odata.type": "#net.atos.dirx.access.odata4.sso.CompositeChallenge",
        "type": "net.atos.dirx.access.odata4.sso.CompositeChallenge",
        "clazz": "CompositeAuthnException",
        "authnSessionId": "{new_authn_session_id}",
        "nextAuthnSteps": [
            {
                "authnMethodId": "{otp_authentication_method_id}",
                "callbackTypes": [
                    "net.atos.dirx.access.odata4.sso.OtpCallback"
                ],
                "challenge": {
                    "@odata.type": "#net.atos.dirx.access.odata4.sso.TokenChallenge",
                    "type": "net.atos.dirx.access.odata4.sso.TokenChallenge",
                    "clazz": "OTPAuthnException"
                }
            }
        ]
    }
}

In the response, there can be seen that the new_authn_session_id parameter was received to represent new state.

Request

POST {sso_rest_web_application_location}/PerformSso
{
    "ssoRequest": {
        "pepId": "{pep_id}",
        "authnMethodId": "{authn_method_id_with_initial_step}"
    },
    "callbackHandler": [
        {
            "authnSessionId": "{new_authn_session_id}",
            "type": "net.atos.dirx.access.odata4.sso.AuthnSessionIdCallback"
        },
        {
            "otpValue": "{otp_password}",
            "type": "net.atos.dirx.access.odata4.sso.OtpCallback"
        }
    ]
}

The otp_password parameter value was received via mail.

Response

{
    "sessionId": "{session_id}",
    "cookies": [
        "DXASIDMYCOMPANY={session_cookie}; Domain={session_cookie_domain}; Path={session_cookie_path}"
    ],
    "redirectUri": "{redirection_target_uri}",
    "status": "OK",
    "isAuthorized": true,
    "inAttrs": [
        {
            "key": "E-Mail",
            "value": "{user_mail}"
        },
        {
            "key": "RoleAssignments",
            "value": "{user_roles}"
        }
    ],
    "inHeaders": [
        {
            "key": "DistinguishedName",
            "value": "{user_dn}"
        }
    ],
    "outHeaders": [
        {
            "key": "UIDs",
            "value": "{user_uid}"
        }
    ]
}

Session Validation

The existing session can be validated based on the JWT of the previous authentication.

The session is represented by sessionId parameter of the ssoRequest complex type.

Request

POST {sso_rest_web_application_location}/PerformSso
{
    "ssoRequest": {
        "pepId": "{pep_id}",
        "sessionId": "{session_id}"
    },
    "callbackHandler": []
}

For more information regarding request parameters, please see the OpenAPI 3.0 document.

Response

{
    "sessionId": "{session_id}",
    "cookies": [
        "DXASIDMYCOMPANY={session_cookie}; Domain={session_cookie_domain}; Path={session_cookie_path}"
    ],
    "status": "OK",
    "isAuthorized": true,
    "inAttrs": [
        {
            "key": "E-Mail",
            "value": "{user_mail}"
        },
        {
            "key": "RoleAssignments",
            "value": "{user_roles}"
        }
    ],
    "inHeaders": [
        {
            "key": "DistinguishedName",
            "value": "{user_dn}"
        }
    ],
    "outHeaders": [
        {
            "key": "UIDs",
            "value": "{user_uid}"
        }
    ]
}

Implementation Details

The SSO REST Web Service is implemented as the OData4 protocol. For the clients that are built according to the OData4 standard, the metadata document can be used and found at {sso_rest_web_application_location}/$metadata.