Overview

You can customize Centrify Identity and Access Management (CIAM) with templates to change the look and feel of your portal. As a developer, however, you might want to go beyond these customizations and provide a completely different user experience. The Centrify Identity Platform API's provide you with a set of RESTful endpoints that enable you to use CIAM functionality in your custom applications.

To use the Centrify Identity Platform APIs, your application must first authenticate the user. Your application uses these two endpoints in the authentication workflow:

• /Security/StartAuthentication: This endpoint tells the server that a user for a given tenant wants to be authenticated. If the user exists, the server returns an array of security challenges to the client, each containing an array of factors, known as mechanisms, that the user must fulfill for each challenge. The user’s responses to these mechanisms are processed via the /Security/AdvanceAuthentication endpoint.
• /Security/AdvanceAuthentication: This endpoint sends the user’s responses to the mechanisms back to the server. If the server accepts these challenges, it returns an authentication token cookie to the client. Once the client receives the authentication token, the client can use it to invoke subsequent endpoints on behalf of the user.

Note: after /Security/StartAuthentication has been successfully invoked, you must complete the authentication process with /Security/AdvanceAuthentication within five minutes.

This following tutorials walk you through the details of invoking these endpoints to authenticate a user from a client application. You can use the Postman extension to your Chrome browser to invoke the endpoints.

• Starting the Authentication Process
• Advancing the Authentication
• Advancing Multi-factor Authentication
• Advancing Out-of-bounds Authentication
• Social Login
• Logging Out
• C# Example

Terms

The following terms are used throughout these tutorials:

• Mechanism: A security factor that a user needs to fulfill as part of a challenge in the authentication process (e.g., providing the correct password, entering the correct SMS response, etc.). A mechanism corresponds to a security factor that has been defined for a challenge profile on the admin portal. An array of one or more mechanisms is returned for each challenge profile once the authentication process is started.
• Challenge: An array of up to two challenges that correspond to the authentication profiles configured in the policy section of the admin portal. Each challenge contains an array of mechanisms. To authenticate, the user must provide the correct response(s) to each mechanism.
• Multi Factor Authentication (MFA): Authentication that requires the user to fulfill mechanisms from two challenges.
• Out-of-Bounds Authentication (OOB): A mechanism involving a third party entity, such as a smart phone (e.g., the user needs to provide the correct SMS response).
• Client: The application that is invoking Centrify endpoints on behalf of a user.
• Identity Provider (IDP): An online service that provides user authentication on behalf of another online service. For example, a client can redirect a user to log in on a social media website which then returns the authentication result to the client.