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.

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.

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

Back to top

URL

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

Back to top

Sample Request

The example below shows a request for SSO login when the user has chosen to log in with Google.

Request URL#1

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

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

Request URL#2

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

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

Request URL#3:

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.

Sample request headers

Accept: application/json

Back to top

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

Back to top

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.

Back to top

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.

Back to top

Sample Response

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

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

Line breaks have been added for display purposes (to the redirect location).

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%3DGoogleAutomation%26finalUrl%3Dhttp%253A%252F%252F{hostname}%253A9900%252Fui%252F
apps%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)

Line breaks have been added for display purposes (to the cookie).

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%2CAttributesIncl
uded%3Dfalse%2CUserFDN%3Da06082f9-a139-485b-aecd-3cce36334188%252Eacmepaymentscorp%2CUserName%3Dhttps%3A%2F%2Fwww%252Egoogle%2
52Ecom%2Faccounts%2Fo8%2Fid%3Fid%253DAItOawnegtajeS9fo4Wg1k_lERFhXQajXDR8JCM%2Csig%3DGvMp8xTb3XT6XsVnlrQae0Etn2_6LOMyFRr
0G-Y2tLLV3BJ9caahwAPEik_cX8Cc_Ar2rCJwoBNvfpIYAMg-S16mqtQ_qLGQUoefu0UM7IhGE3LaWdh41y-Gwcir_pOoD1-zRleY9oSdH-dWHm2rfWHWmXKlu
VljKGd2q6kXBzU;path=/;expires=Wed, 25-Jun-2014 21:34:47 GMT;HttpOnly;Version=1

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

Line breaks added for display purposes (in authTokenString)

{
  "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%2C
UserName%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"
  }
}

Back to top

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).

Back to top

Response Body

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

Back to top

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.

Back to top

Related Topics