GET /api/login/ssoLogin

Allows a user to log in by authenticating with an external identity provider that has its own login screen, providing SSO is enabled between the platform and the identity provider. Examples: Facebook, Google. SSO must already be enabled between the platform and the identity provider; the System Admin must have already created the OpenID Connect domain and enabled it for login.

For example, this operation is generally used when SSO login uses a redirect URL to accomplish the login. In this case, the Domain ID is sent as a query or path parameter rather than POST data.

Note: Login domains might support SSO login via POST or GET. For example, an OpenID Connect Relying Party domain might support a response mode of query, fragment, or form_post. If the domain supports form_post, POST /api/login/ssoLogin is used. If the domain supports query or fragment, GET /api/login/ssoLogin is used.

This operation initiates the login process. Other operations might be needed to move the user through the login process including completing any login tasks.

Note: for an example of SSO login using a SAML domain, including request and response, see Example: SSO login with SAML Provider.

The GET /api/login/endsession operation is used to terminate the login session.

This operation redirects the user to the identity provider selected so that the identity provider can authenticate the user. The identity provider:

  1. Checks if the user is already logged in. If the user isn't logged in, presents a login screen for the user to log in.
  2. Once the user is logged in, returns confirmation that the user has been authenticated, and returns specific information about the user; for example, first name, last name, and email address. The specific data returned depends on the specific provider and configuration scenario.

If the optional finalURL parameter is included, the identity provider also redirects the user to the specified URL once authentication is complete.

Authorization Roles/Permissions: To complete this operation successfully, a user must have valid credentials for the login connector specified in the domain parameter. Note that support of specific login connectors is configurable and is therefore not the same on all platform instances.

This topic includes the following sections:

HTTP Method

GET

URL

https://{hostname}/api/login/ssologin

Sample Request

The examples below show SSO login in different scenarios, with different providers.

Request URL #1: Domain in query parameter

In the example below, the domain name is in a query parameter. The response will include the LoginData object, login cookie, and CSRF cookie if applicable.

http://www.acmepaymentscorp.com/api/login/ssoLogin?domain=Googleacmepaymentscorp

Request URL #2: domain in path parameter

In the example below, the domain name is in a path parameter. The response will include the LoginData object, login cookie, and CSRF cookie if applicable.

http://www.acmepaymentscorp.com/api/login/ssoLogin/Googleacmepaymentscorp

Request URL #3: includes optional finalURL parameter

This example includes the finalURL parameter. The domain name is in a query parameter. The URL is accessed in a new tab.

http://www.acmepaymentscorp.com/api/login/ssoLogin?ssoRetryCount=0&domain=siochain-prod-siteminder&finalUrl=https%3A//developer.siochain.com/xyz

In the above example, the API redirects the browser to the following URL:

https://acmecorp.com/newpage?status=success&userID=c28217f4-879a-4045-9abb-b018b4f59700.acmepaymentscorp&userState=registered

In the above example, the status, userID, and userState parameters are added. The platform cookie, and CSRF cookie if applicable, will be in the response.

Request URL #4: SAML identity provider

This example is a call to a SAML domain. For SAML, you will need to run this operation, then a call to the SAML identity provider, and then a call to the POST /api/login/ssoLogin operation.

For a full example of SSO login using a SAML domain, including request and response, see Example: SSO login with SAML Provider.

GET /api/login/ssoLogin, request

Sample request headers 

Accept: application/json

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header Description
Accept application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json

Request Parameters

Parameter Parm Type Data Type Required Description
domain Query string Optional

(Required unless domain is sent as a path parameter)

The login domain the user has selected for logging in.
domain Path string Optional

(Required if domain is not sent as a query parameter)

The login domain the user has selected for logging in.

Note: the platform looks first for the query parameter, then for the path parameter.
finalURL Query string Optional

The URL to which the login provider should return the user once the login provider has completed the authentication process. If this parameter is provided, this operation redirects the user to the specified URL, along with userID, status, and userState query parameters. If it isn't provided, the operation returns information in a JSON object.

Instead of returning a LoginData response it redirects the browser to the finalURL value.

Response

If successful, this operation returns one of these:

  • If finalURL parameter was provided: HTTP status code 307, with the temporary redirect location.
  • If finalURL prameter was not provided: HTTP status code 200, with the user authentication information in JSON format.

Sample Response

The sample response below shows the authentication information returned from Google.

Sample response header (Request #1: finalURL parameter provided in request) 

HTTP/1.1 307 Temporary Redirect
Location: https://www.google.com/accounts/o8/ud?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.return_to=http%3A%2F%2F{hostname}%3A9900%2Fapi%2Flogin%2FssoLogin%3Fdomain%3DGoogleacmepaymentscorp%26finalUrl%3Dhttp%253A%252F%252F{hostname}%253A9900%252Fui%252Fapps%252Facmepaymentscorp%252F_VzIIxu3KZVLI9OE54nLgNnQ%252Fresources%252Fconsole%252Fglobal%252Frelyingpartypostlogin.html%253Fdynamic%253Dtrue%2526baseUrl%253Dhttp%253A%252F%252F{hostname}l%253A9900%252Facmepaymentscorp%26ssoRetryCount%3D0&openid.realm=http%3A%2F%2F{hostname}%3A9900&openid.assoc_handle=1.AMlYA9VUmHqfKXB6FDt6oPqbXQltnJwUq-cp3pCesTn_Z8HnsXu4nxfL5848Bp25qpzq_DsrHRX2Zg&openid.mode=checkid_setup&openid.ns.ext1=http%3A%2F%2Fopenid.net%2Fsrv%2Fax%2F1.0&openid.ext1.type.email=http%3A%2F%2Faxschema.org%2Fcontact%2Femail&openid.ext1.type.lastname=http%3A%2F%2Faxschema.org%2FnamePerson%2Flast&openid.ext1.type.firstname=http%3A%2F%2Faxschema.org%2FnamePerson%2Ffirst&openid.ext1.type.fullname=http%3A%2F%2Faxschema.org%2FnamePerson&openid.ext1.required=firstname%2Clastname%2Cemail%2Cfullname&openid.ext1.mode=fetch_request

Sample response header (Request #2: no finalURL parameter) 

Status Code: 200 OK
Content-Type: application/json
Set-Cookie: AtmoAuthToken_acmepaymentscorp=TokenID%3D09e80883-fcad-11e3-9389-f3b8a6785a3a%2Cclaimed_id%3Durn%3Aacmepaymentscorp%3Auser%3Aacmepaymentscorp%3Aa06082f9-a139-485b-aecd-3cce36334188%2CissueTime%3D1403730587730%2CexpirationTime%3D1403732387699%2CAttributesIncluded%3Dfalse%2CUserFDN%3Da06082f9-a139-485b-aecd-3cce36334188%252Eacmepaymentscorp%2CUserName%3Dhttps%3A%2F%2Fwww%252Egoogle%252Ecom%2Faccounts%2Fo8%2Fid%3Fid%253DAItOawnegtajeS9fo4Wg1k_lERFhXQajXDR8JCM%2Csig%3DGvMp8xTb3XT6XsVnlrQae0Etn2_6LOMyFRr0G-Y2tLLV3BJ9caahwAPEik_cX8Cc_Ar2rCJwoBNvfpIYAMg-S16mqtQ_qLGQUoefu0UM7IhGE3LaWdh41y-Gwcir_pOoD1-zRleY9oSdH-dWHm2rfWHWmXKluVljKGd2q6kXBzU;path=/;expires=Wed, 25-Jun-2014 21:34:47 GMT;HttpOnly;Version=1

Sample response body (Request #2: no finalURL parameter) 

{
  "state" : "registered",
  "status" : "Active",
  "authTokenString" : "TokenID%3D09e80883-fcad-11e3-9389-f3b8a6785a3a%2Cclaimed_id%3Durn%3Aacmepaymentscorp%3Auser%3Aacmepaymentscorp%3Aa06082f9-a139-485b-aecd-3cce36334188%2CissueTime%3D1403730587730%2CexpirationTime%3D1403732387699%2CAttributesIncluded%3Dfalse%2CUserFDN%3Da06082f9-a139-485b-aecd-3cce36334188%252Eacmepaymentscorp%2CUserName%3Dhttps%3A%2F%2Fwww%252Egoogle%252Ecom%2Faccounts%2Fo8%2Fid%3Fid%253DAItOawnegtajeS9fo4Wg1k_lERFhXQajXDR8JCM%2Csig%3DGvMp8xTb3XT6XsVnlrQae0Etn2_6LOMyFRr0G-Y2tLLV3BJ9caahwAPEik_cX8Cc_Ar2rCJwoBNvfpIYAMg-S16mqtQ_qLGQUoefu0UM7IhGE3LaWdh41y-Gwcir_pOoD1-zRleY9oSdH-dWHm2rfWHWmXKluVljKGd2q6kXBzU",
  "response" : {
    "pendingNotifications" : 0,
    "loginDomainID" : "56bd0bfa-b3d9-406e-8d11-5bccf300efb8.acmepaymentscorp",
    "userFDN" : "a06082f9-a139-485b-aecd-3cce36334188.acmepaymentscorp",
    "userName" : "JaneSaoirse"
  }
}

Sample response body (Request #4: SAML)

To view the response body for the SAML example, and step-by-step instructions to complete the SAML login, see see Example: SSO login with SAML Provider.

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header Description
Content-Type application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json
Location The URL the user is redirected to, for authentication by the identity provider (only if finalURL parameter was included in the request).

Response Body

Name Type Description
LoginData LoginData Contains data associated with a user's login.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item Value
500 An error occurred processing the call.

More information about Akana API Platform API error messages.