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.
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.
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):
Sample request body/parameters (SAML):
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:
Sample 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:
Response cookies—AtmoAuthToken_{fedmember}:
Response cookies—Csrf-Token_{fedmember}:
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.