With the REST APIs you can enable external users (such as customers or temporary contractors) to use their existing social media credentials to log into the Centrify user portal. Once authenticated, users can do the following:

Access assigned applications.
Add applications to the Apps page.
View their account information and user portal activity history.

Users who log in via social media are automatically added to the Everybody role and the External Users group. By applying a role to the External Users group you can easily assign access to a standard set of applications to all external users.

The current topic shows you how to call the REST APIs to authenticate a user via socail media credentials.

Setting up a trust relationship with an IDP

Before you can authenticate users through social media, you must set up a trust relationship with a social-identity provider (IDP). Identity Platform supports these IDPs:

Facebook
Google
LinkedIn
Microsoft

You can set up a trust relationship with an IDP in Cloud Manager as shown here:

Enabling IDPs for authentication:

Log in to Cloud Manager and click Settings, Users, Social Login.
Select one or more of the social-identity providers, for example, Facebook.
Click Save to save your selections.

For each IDP that you enable, Identity Platform creates a user-access page, or application, for login. When authenticating through social media, you send a user to this page.

Calling the API for social-media authentication

Identity Platform employs a callback mechanism to communicate with an IDP. When Identity Platform sends a user to the IDP access page for authentication, it passes a callback function that includes the client's tenant ID and an ID for the MFA session. After validating the user's credentials, the IDP executes the callback function to return the user to the client's login session.

The first step in validating a user through social media is to contact the social identity provider (IDP) to use for authentication by calling /Security/StartAuthentication. This function takes a single parameter, IdpName, with a keyword to identify the IDP to contact. For example, to request authentication for a user through Facebook:

/Security/StartSocialAuthentication
    {IdpName: "Facebook"}

The call returns a response similar to the following:

IdpRedirectUrl=https://www.facebook.com/dialog/oauth?client_id=1513153205663776&redirect_uri=https%3a%2f%2fpod1.centrify.com%2fSocialAuth%2fFacebookAuthCallback&state=ABC0123-64f226d5-a237-42dd-b344-897234189534&response_type=code&scope=public_profile,email 
Status=RedirectToIdp

The call creates an MFA session and a callback function to pass to Facebook. In the response:

Status=RedriectToIdp indicates that the user has been redirected to an IDP for login.
IdpRedirectUrl contains the callback function to pass to Facebook.

The IdpRedirectUrl callback function contains the following elements:

https://www.facebook.com/dialog/oauth?client_id=1513153205663776 specifies the Centrify-specific user-access page for Facebook.
redirect_uri=https%3a%2f%2fpod1.centrify.com%2fSocialAuth%2fFacebookAuthCallback identifies the REST API function to call when Facebook calls back to Identity Platform.
state=ABC0123-64f226d5-a237-42dd-b344-897234189534 includes the tenant ID (ABC0123) and the MFA session ID (64f226d5...).
response_type=code specifies that code is the expected response.
scope=public_profile,email identifies the elements to return from Facebook.

Note: If you created a customized user-access page and configured it in Cloud Manager, the function automatically returns the ID for your customized page in client_id.

The client needs to save IdpRedirectUrl and pass it to a browser to send the user to the Facebook user-access screen:

https://www.facebook.com/dialog/oauth?client_id=1513153205663776&
redirect_uri=https%3a%2f%2fpod1.centrify.com%2fSocialAuth%2fFacebookAuthCallback&
state=ABC0123-64f226d5-a237-42dd-b344-897234189534&
response_type=code&
scope=public_profile,email

After the user provides credentials, Facebook returns the user to the original MFA session by executing the callback function:

https://pod1.centrify.com/SocialAuth/FacebookAuthCallback
{
"code": AQBGtF1mNRKICYoJyUZueV8mo7kvsVe6F4Klph2eJUQ1naL-GDqHMxf_NIY7JmLLhnVOIfTFGu-sJC6oERVX7R1kjofFiP_z_KM8e5-pbZGMwW9BSNML6gSgjR1AEiiKwHLfeqQwqdZA2WZYYr7QS52q0q8P76B6Y8TN5ivEhvBBNgClhlxXC7bqkiYYkB_Uchc0wAB3x_jeSw5jHkGbNimWRz4-wo1ylk5bV8YSioiFHE8QwfuoNc7H-hFqWF1mmvuVIJOhYA03zeX6lCk61FApqEuPcMKIRrRnLE8S8ULr0k9Pu7QS5Gnr66l-9nyCsJbeJkSimQkcR1zxEs9AnHGz
 "state": ABC0123-64f226d5-a237-42dd-b344-897234189534
}

For a successful login, the function returns a URL similar to the following:

https://acme.my.centrify.com:443/my?customerId=ABC0123&ExtIdpAuthChallengeState=ABC0123-64f226d5-a237-42dd-b344-897234189534&username=ausem%40mac.com

The URL identifies the Identity Service login session that called Facebook to authenticate the user, and provides the email name of the user. Pass this URL to a browser, then call /Security/ResumeFromExtIdpAuth to log in the user:

https://acme.my.centrify.com:443/my?customerId=ABC0123&ExtIdpAuthChallengeState=ABC012364f226d5-a237-42dd-b344-897234189534&username=auser%40mac.com
/Security/ResumeFromExtIdpAuth

/Security/ResumeFromExtIdpAuth returns results similar to the following sample response:

{
"success":true,
"Result":
 {
  "AuthLevel":"Normal",
  "DisplayName":"Allen Usem","Auth":"B6A7A89962BC...",
  "UserId":"db6244dd-8632-5748-664e-225c700432a7",
  "EmailAddress":"[email protected]",
  "UserDirectory":"FDS",
  "PodFqdn":"acme.my.centrify.com",
  "User":"[email protected]",
  "CustomerID":"ABC0123",
  "SystemID":"ABC0123",
  "SourceDsType":"FDS",
  "Summary":"LoginSuccess"
 },
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null}

"Summary":"LoginSuccess" indicates that the user was successfully authenticated and logged in.

If social-media users are configured for multi-factor authentication, you must supply one or more additional challenges after a user is successfully authenticated by the IDP and returned to the login screen. In this case, "Summary":"NewPackage" indicates that the call to /Security/ResumeFromExtIdpAuth has returned a new MFA package that contains one or more challenge mechanisms for the user to respond to.

The following MFA sample response shows a new package with a single email challenge returned by /Security/ResumeFromExtIdpAuth:

{
"success":true,
"Result":
{
 "ClientHints":
  {"PersistDefault":false,"AllowPersist":false,"AllowForgotPassword":false},
 "Version":"1.0",
 "SessionId":"jf3eH91wqUqy2sxQQAokuoGCS9uJ63EIoLNLVAbZ60E1",
 "Challenges":
  [{"Mechanisms":
   [{
    "AnswerType":"StartOob",
    "Name":"EMAIL",
    "PromptMechChosen":"Click the link in the email sent to [email protected]",
    "PromptSelectMech":"Email... @mac.com","PartialAddress":"mac.com", 
    "MechanismId":"ZbaHqYKZFUyI45AP0sYUgMXK5IaIzJH8YiIAy9ekklk1"
   }]
  }],
 "Summary":"NewPackage",
 "TenantId":"ABC0123"
}, 
 
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null}
 
 
 
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null}

To respond to the email challenge, call /Security/AdvanceAuthentication as follows:

/Security/AdvanceAuthentication
{
  "Action":"StartOOB"
  "TenantId":"ABC0123",
  "SessionId":"yjShZPWrJJXMN0yYTqSe5HT4nUVj0IZOkhcsmmxhnug1",
  "PersistentLogin":false,
  "MechanismId":"pNzgA4BjTAbmh3Ldc5DT_QQxdoyA8kRMppSPA5oEcrE1",
 }

Until the user responds to the email challenge, this call returns "Summary":"OobPending".

Call /SecurityAdvanceAuthentication with the same TenantId, SessionId, and MechanismId — but specify "Action":"Polling" — and check Summary until you see "LoginSuccess"` indicating that the user has successfully answered the email challenge:

/Security/AdvanceAuthentication
{
  "Action":"Polling"
  "TenantId":"ABC0123",
  "SessionId":"yjShZPWrJJXMN0yYTqSe5HT4nUVj0IZOkhcsmmxhnug1",
  "PersistentLogin":false,
  "MechanismId":"pNzgA4BjTAbmh3Ldc5DT_QQxdoyA8kRMppSPA5oEcrE1",
 }

Authenticating users explains in detail how to respond to challenge mechanisms, including multiple challenges in addition to user/password challenges.

Setting up a trust relationship with an IDP

Calling the API for social-media authentication

See Also