POST /api/login/ssoLogin

Logs the user in to an external identity system such as Google or Facebook, for a login domain set up on the platform.

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.

The specific processing that occurs with this operation depends on the login domain being used, as specified in the domain parameter in the request message. For example:

  • OpenID Connect Relying Party domain (includes Google and Facebook connectors in the platform): the platform references the domain setup, applying the OpenID Connect specification to see what should be used for the SSO token; for example, id_token. For an example, see Sample request #2: Google and Sample response #2: Google.
  • CA Siteminder domain: the operation looks for the SMSESSION cookie header.
  • SAML Web SSO domain: it looks for the SAML assertion in query or form parameters.

With SSO Login, depending on the domain being used, and the protocol that it implements, the requirements of the request message are different.

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

Authorization Roles/Permissions: Anyone can run this operation.

This topic includes the following sections:

HTTP Method

POST

URL

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

Sample Request #1: LDAP

The examples below shows an SSO login request for an LDAP domain. The first example sends the domain parameter in the POST content, the second sends it in the path.

In processing the request, the platform looks for the domain parameter first in the POST content, and then in the path.

Request URL #1-1 (LDAP)

Domain parameter is not included in the path, it is sent in the POST content (see sample request body #1).

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

Request URL #1-2 (LDAP)

Domain parameter is sent in the path, and other parameters are sent in the POST content (see sample request body #2).

http://acmepaymentscorp.com/api/login/ssoLogin/Ldapacmepaymentscorp1acmepaymentscorp

Sample request headers

Host: {hostname}
Accept: application/json, text/javascript, */*; q=0.01
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Sample request body #1 (LDAP)

identity_username=MaryMartinson&secret_password=MyPassword11&domain=Ldapacmepaymentscorp1acmepaymentscorp

Sample request body #2 (LDAP)

identity_username=MaryMartinson&secret_password=MyPassword11

Sample Request #2: Google

The example below shows login via Google. In this scenario, the Site Admin must first set up an OpenID Connect Relying Party domain, and then enable the domain for login.

Then, users can log in by using their Google credentials. The platform sends a message to Google, and Google either collects the user's credentials and then returns the token, or else returns the token immediately if the user is already logged in. This call then logs the user in to the platform using the token from Google, as shown below, and returns the authentication cookies.

Sample request URL and headers (Google):

The example below shows the request headers in Postman.

login_ssoLoginPost: request headers

Sample request body/parameters (Google):

The example below shows the request body in Postman.

The domain is the name of the domain that the Site Admin set up in the Community Manager developer portal. The ID token is returned by your provider after authenticating the user.

login_ssoLoginPost: request body

Sample Request #3: SAML

To log in with SAML as the identity provider, first make a call to the GET /api/login/ssoLogin operation, then a call to the SAML identity provider, and then a call to this operation to complete the login process.

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

Sample request URL and headers (SAML):

POST /api/login/ssoLogin, request headers

Sample request body/parameters (SAML):

POST /api/login/ssoLogin, request body

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
Content-Type application/x-www-form-urlencoded

Request Parameters

Parameter Parm Type Data Type Required Description
domain Form String Required Unique ID for the valid platform login domain that the user has chosen to log in on.

Response

If successful, this operation returns HTTP status code 200, and the user's login request is processed. If all other login tasks are complete, the user is logged in. If not, the user is directed to the next login task.

Sample Response #1: LDAP

The sample response below shows successful completion of this operation.

Sample response headers

HTTP/1.1 200 OK
Content-Type: application/json
Expires: Mon, 28 Sep 2015 15:23:14 GMT
Set-Cookie: SignupToken_acmepaymentescorp=Fbnw5YUYLtPVfzTCxtriPKVdB9m7xO7ALwGyt8_f2MiZg
1393OGQISkdqSwAtm-1nakXzGLmC_uw3ipUj-ZlHY5NhVjuykWvri5pKVNJhJPyKs2gLN_40SkKGJ7Dc
DDLTPi4id31yKJ6CDFPCEK7OSycu3fpuvYCCwDv_pfKE5kFrOtW1mFN2whcUNhboAyT9KioLrKREdBr7kc8c

Sample response body #1-1

User is logged in.

{
  "state" : "registered",
  "response" : {
    "userName" : "Engineering100user100",
    "loginState" : "login.complete",
    "loginDomainID" : "f6b0cfa2-7985-4363-9dc7-8f00df8ea83a.acmepaymentescorp",
    "userFDN" : "9b633341-0aa9-4160-8f81-b70c55355aaf.acmepaymentescorp",
    "pendingNotifications" : 0
  },
  "status" : "Active"
}

Sample response body #1-2

In the example below, the user still needs to accept the signup agreement, so the user's state value is pending_validation. The user is redirected to a page for accepting the agreement.

{
  "state" : "pending_validation",
  "status" : "Disabled",
  "response" : {
    "userName" : "Engineering100user100",
    "pendingAgreements" : [ "signupagrmtv1.acmepaymentescorp" ],
    "loginDomainID" : "1d3c5eaf-f575-4844-be74-fc94eb091479.acmepaymentescorp",
    "userFDN" : "64471a3a-16c4-42d4-b09d-e12e8294f927.acmepaymentescorp",
    "pendingNotifications" : 0
  },
  "signupCode" : "Fbnw5YUYLtPVfzTCxtriPKVdB9m7xO7ALwGyt8_f2MiZg1393OGQISkdqSwAtm-1nakXzGLmC_uw3ipUj-
ZlHY5NhVjuykWvri5pKVNJhJPyKs2gLN_40SkKGJ7DcDDLTPi4id31yKJ6CDFPCEK7OSycu3fpuvYCCwDv_pfKE5kFrOtW1mFN2whcUNhboAyT9KioLrKREdBr7kc8c"
}

Sample Response #2: Google

The example below shown an HTTP 200 response code returned, with the AtmoAuthToken_{fedmemberid} platform cookie and X-Csrf-Token_{fedmemberID} CSRF cookie, which which are needed for further API calls.

Sample response headers:

login_ssoLoginPost: response

Sample response body:

login_ssoLoginPost: response body

Sample Response #3: SAML

The SAML response is shown below. The user is registered and logged in, and the platform cookies are returned.

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

Sample response body:

POST /api/login/ssoLogin, response body

Response cookies—AtmoAuthToken_{fedmember}:

POST /api/login/ssoLogin, response body, login cookie

Response cookies—Csrf-Token_{fedmember}:

POST /api/login/ssoLogin, response body CSRF cookie

Note: As well as the login cookie and CSRF cookie, certain operations require specific roles. For example, to create an API, a user who logs in via an external domain would need an additional role, such as being invited to the API Admin group and accepting the invitation. This scenario would use the POST /api/groups/{GroupID}/members and POST /api/groups/requests/{MembershipRequestID}/actions operations. After that, the user could add an API using the POST /api/apis operation.

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

Response Body

The response body depends on the domain used.

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.