1. Integration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.1 Granting temporary access to public server for SCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.2 OAuth 2.0 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 OAuth 2.0 Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 OAuth 2.0 Integration Endpoints, Sample Requests, and Sample Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5 PingFederate: SAML Vs OpenToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6 PingFederate and CloudHSM Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7 PingFederate OAuth Vs OpenAM OAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8 PingFederate TimeOut Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9 SocialIDM User Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10 User Profile Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1 User Profile Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 Add User Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.2 Get User Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.3 Update User Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.4 Search Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.5 Deactivate an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.6 Link/Unlink Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Credential Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Credential Management: Admin Password Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2 Credential Management: Change Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.3 Credential Management: Get Credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.4 Credential Management: KBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.5 Credential Management: OTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Sample JSON Payloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2
2
2
3
12
14
14
15
16
16
21
25
27
27
27
29
30
33
34
34
34
35
36
38
41
43
44

Integration Guide
Refer to the following chapters for integration:
Granting temporary access to public server for SCP
OAuth 2.0 Clients
OAuth 2.0 Integration
OAuth 2.0 Integration Endpoints, Sample Requests, and Sample Responses
PingFederate: SAML Vs OpenToken
PingFederate and CloudHSM Integration
PingFederate OAuth Vs OpenAM OAuth
PingFederate TimeOut Values
SocialIDM User Instructions
User Profile Integration

Granting temporary access to public server for SCP

Setting up Access
To provide scp access without shell access:
1.

Install rssh package on host

a. yum install rssh
b. chmod og+rx /usr/bin/rssh

For each user to be added (username ncr1 as an example)

1. Create unix account on EC2-host
a. useradd -m -d /home/ncr1 -s /usr/bin/rssh ncr1
2. Ask Account owner to generate ssh keypair using ssh-keygen ; and send ssh public key to us.
3. Drop received ssh public key to user's .ssh/authorized_keys
a. mkdir /home/ncr1/.ssh
b. chown ncr1 /home/ncr1/.ssh
c. chmod 600 /home/ncr1/.ssh
4. The default for rssh is deny all scp and sftp access. Enable ncr1 to use scp under rssh, by adding the following line to /etc/rssh.conf
a. user=ncr1:011:00001:

Disable Access
1. To Disable ncr1 user to use scp, remove the above line, or change it to :
a. user=ncr1:011:00000:

Process to grant access

1. Access is via scp using ssh keypairs. ( scp allows moving files only and has no GUI support. sftp is required for listing contents and
directory operations.)
2. 2. Client requiring access need to generate ssh keypair and send us the public key. The key should be SSH2 1024-bit RSA.
a. On windows running putty, use puttygen. Refer to Putty documentationhttp://winscp.net/eng/docs/ui_puttygen#obtaining_and_st
arting_puttygen
b. On OS/X or linux, the command to generate ssh key is usually ssh-keygen .
3. Transfer the ssh public key to CRN Ops.
4. CRN Ops use the steps above to grant user scp/sftp access; and provide the connection info once setup is completed.

Connection Information
Name

IP Address

Public IP for OpenVPN

54.84.22.12

Intranet IP

10.0.0.171

OAuth 2.0 Clients

Clients Configured
Following are the clients configured in PingFederate:
Client Id

Component

Grant Types Supported

Pl0QC2Y1fAxX57V5K2uFcarVjDbflN

SocialIDM

Resource owner password credentials Grant type

pingfederate

PingFederate

Resource owner password credentials Grant type

axway_rs

AxWay

urn:pingidentity.com:oauth2:grant_type:validate_bearer

lS9qHlAEZwY4pSC4fIucAkzdemcaF8

NCR Mobile Ordering Mobile App

authorization_code

6BE789472A038F0292AE1BD022434A

NCR Mobile Ordering Resource Server

urn:pingidentity.com:oauth2:grant_type:validate_bearer

MobileAppV1

Chick-fil-A Flag Ship Mobile App

authorization_code

W6K5MVJSpEIsiIxmdO7KrtZKZXtgch

Chick-fil-A Testing Team

Resource owner password credentials Grant type

OAuth 2.0 Integration

Introduction
Chick-fil-A, Inc is engaged in a multi-year, multi-phased project to build a Customer Identity Management System to centralize the functionality of
authentication, authorization, and user management. The integrating service providers can leverage this system for the following:
1. Authentication
2. Authorization to access an HTTP Service
3. RESTful API to access user's identity profile based on authorization granted as part of the step 2.
The document describes integration capabilities of Customer Identity Management System and to define the integration interfaces.

Glossary
Term

Definition

Resource server
(API server)

The server that hosts the protected resources, capable of accepting and responding to the protected resource requests
by using the access tokens.

Client/Application

An application that makes the protected resource requests on behalf of the end user. The term "client" does not imply
any particular implementation characteristics, for example, whether the application executes on a server, a desktop, or
other devices.

Authorization
server

The server that issues access tokens to the client after successfully authenticating the resource owner and obtaining
authorization.

Authorization
Code/Authorization
Token

The authorization code is obtained by using an authorization server as an intermediary between the client and the end
user. It is used to authenticate the client and grant the transmission of the access token. This is the token that
authorization server issues to the clients that can be swapped for an access token. It has a very short lifetime since the
swap must be performed immediately after users provide their authorization.

Access Token

A token required to access the resources protected by OAuth 2.0. The access token has an expiry time and is active for
12 minutes.

Refresh Token

A token that the authorization server issues to clients and can be swapped for a brand new access token, without
repeating the authorization process. The refresh token has an expiry time and is active for 30 days.

References
Reference Documentation
OAuth 2.0 Specification
Refer to this location http://tools.ietf.org/html/rfc6749 for the final version of the specification.

OAuth 2.0 Clients

Refer to this location http://oauth.net/2/ to view OAuth 2.0 Clients.

OAuth 2.0 Development Tools

Tool

Location

Chrome REST Client

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo?hl=en-US

Firefox REST Client

https://addons.mozilla.org/en-US/firefox/addon/restclient/

Standards in Solution
OAuth 2.0
OAuth 2.0 is the Authorization standard used in this proposed solution. As per RFC, OAuth 2.0 authorization framework enables a third-party
application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the
resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. In simple terms, OAuth
provides an API based security solution that does not require customers to pass on their user name and password to the resource server.

Integration
Refer to Figure 1 that depicts the integration process.

Figure 1: Integration process

Registration
All applications that can access a Chick-fil-A APIs must be registered. The registration is currently an offline process. The result of this registration
process is a client ID, and client secret shared between Chick-fil-A and integrating application. The set of variable values is based on the type of
application that you are building. For example, a JavaScript application does not require a secret, but a web server application requires.

Integration With OAuth Authorization Server

To begin by using OAuth 2.0, the integrating client requires the following details:
The URL of the service being accessed.
The Auth scope, which is a string that defines the specific type of access app, is asking for.
A client ID and client secret, which are strings that identify the app to the service. OAuth 2.0 requires client registration that limits the API
access to register the clients only. Within Customer Identity Management System, client_id and client_secret are required for client
authentication. The service integration team must obtain these strings directly from the Customer Identity Management team.

Environment
Specific End-Point URLs

Environment

End-point URL's

Dev

https://login.dev.crndev.chick-fil-a.com

Stage

https://login.qa.crndev.chick-fil-a.com

Prod

https://login.chick-fil-a.com

Note: Use a dynamic configuration file to access these URLs. The service URLs may change as part of the service upgrade.

OAuth 2.0 End-Points

Use

End-point

Description

Authorization
code

/as/authorization.oauth2

Used by the OAuth AS to interact directly with the resource owners, authenticate them, and obtain
authorization.

Access
token

/as/token.oauth2

Used by the client to obtain an access token and possibly a refresh token by presenting its
authorization grant/refresh token. This endpoint accepts only the HTTP POST method.

Token
Validation

/as/token.oauth2

Used by the client to validate an access token.

Token Info

/oauth2/tokeninfo

Getting token information

OAuth Grants
There are four different types of OAuth 2.0 grants, they are:
1.
2.
3.
4.

Authorization code grant

Implicit grant
Resource owner password credentials grant
Client credentials grant

The OAuth Grant, which is used in this solution, is an Authorization code grant. The scenarios explained below are based on Authorization code
grant.

OAuth 2.0 Authorization Grant

The authorization code grant starts with the client, redirecting the resource owner's user-agent to the PingFederate authorization service. After
authenticating the resource owner and obtaining the resource owner's authorization, PingFederate redirects the resource owner's user-agent back
to the client with an authorization code that the client uses to request the access token.
Figure 2 outlines a successful process from the initial client redirection to the client accessing the protected resource.

Figure 2: Authorization code grant sequence

Scopes Within the Solution

The authorization scope is a string that defines the specific type of access the application is asking for. The scope in this solution is usually a
service URI. The Chick-fil-A authorization server does not explicitly prompt the end user for authorization. The authorization server currently
grants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i nformatio
n service call.
Scope

User Attributes Accessible

//TODO
//TODO

Integration With OAuth Resource Server

REST Web Services Security
All the incoming requests are authenticated based on OAuth 2.0.
Unless specified, all the REST web services must send a valid OAuth 2.0 access token in the header.

Including OAuth Access Token (REST Web Services)

For all the REST Web Service, the OAuth Access token must be included in the HTTP header. The name and format of the HTTP header is as
follows:

Name

Value

Header Name

Authorization

Header Value

Bearer <<OAuth Access Token>>

Example

Authorization: Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4

Using Refresh Token

A refresh token is a string that represents the authorization granted to the client by the resource owner. The string is usually not visible to the
client. The token denotes an identifier used to retrieve the authorization information. Unlike access tokens, refresh tokens are intended for use
only with the authorization servers and are never sent to the resource servers.

Figure 3: Refreshing an expired access token

Sample Use Cases and Screenshots

The given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type. For
complete end point details please refer to : OAuth 2.0 Integration Endpoints, Sample Requests, and Sample Responses

End-Point URL to Authorize

HTTP (GET):https://login.dev.crndev.chick-fil-a.com/as/authorization.oauth2?pfidpadapterid=HtmlFormC&response_type=code&client_id=Mobile
AppV1&scope=/sessionid/me&redirect_uri=http://localhost:9090/redirect
<<REDIRECT_URL>> is the final URL, which the webpage is redirected upon successful authentication and authorization. The mobile app must
detect the URL, retrieve the authorization code from the query string, and close the webview.
Figure 4 depicts the sequence to obtain the access and refresh tokens.

Figure 4: Sequence for obtaining the access and refresh tokens

Refer to the following screenshots on how to obtain an authorization code.

HTTP: Get to the above URL in a web page, and the logon page opens.

Figure 5: Logon page

Enter the username and password.

Figure 6: Entering user credentials

The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning: https://<<REDIRECT_URL>>?code=<<
oauth_authorization_code>>
The code oauth_authorization_code is reused at the next step to trade it for the access token and refresh token.

End-Point URL to Access an Access Token

HTTP (POST):
https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwAB&grant_type=authorization_co
de&client_id=MobileAppV1&redirect_uri=<>
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code.
Access token and refresh tokens are returned as JSON.

Figure 7:End-Point URL to access an access token

Endpoint for Obtaining Access Toke Based on Refresh Token

HTTP (POST):
https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?grant_type=refresh_token&refresh_token=<<REFRESH_TOKEN>>
Example: curl command is: curl \ --request POST \ --data
"grant_type=refresh_token&refresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V" \
A successful sample response looks like:

Access token based on Refresh Token Response

{ "token_type": "Bearer", "expires_in": 599, "refresh_token":
"9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d", "access_token":
"TW6kHy0TmtknIMitAvmcChT3NgDs" }

Getting Token info

HTTP (GET):
https://login.dev.crndev.chick-fil-a.com/oauth2/tokeninfo?access_token=<<ACCESS_TOKEN>>

A successful sample response looks like:

Access token based on Refresh Token Response

{
"scope": [ "/confirmtxns", "/sessionid/me", "/giftcard/me", "/user/profile" ],
"token_type": "Bearer",
"expires_in": 693,
"uid": "CFAID-BEWT6DAVE8",
"mail": "test.user1@demo.com",
"cn": "Test User1",
"realm": "/external",
"access_token": "08857e6c-69ac-4e5d-957d-e1eb04f78d23"
}

OAuth 2.0 Integration Endpoints, Sample Requests, and Sample

Responses
End Points for Authorization Code Grant Type
To obtain Authorization code: /POST
https://login.dev.crndev.chick-fil-a.com/as/authorization.oauth2?pfidpadapterid=HtmlFormC&response_type=code&client_id=<<client_id
>>&redirect_uri=http://localhost:9090/redirect
To obtain OAuth access token: /POST
https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?code=<<authorization_code>>&grant_type=authorization_code&client_id=<<clie
nt_id>>&redirect_uri=http://localhost:9090/redirect

Endpoint for Resouce Owner Password Crendetials Grant Type

To obtain OAuth access token: /POST
https://login.qa.crndev.chick-fil-a.com/as/token.oauth2?grant_type=password&client_id=<<client_id>>&username=<<cfa_mail_id>>&pas
sword=<<cfa_password>>&redirect_uri=http://localhost:9090/redirect

End Point for urn:pingidentity.com:oauth2:grant_type:validate_bearer Grant

Type/Validating an Access Token
Access the following URL by replacing the <<access_token>> with the appropriate value.
HTTP POST with basic authentication (Oauth client ID as user name and client secret as user password):
https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?grant_type=urn:pingidentity.com:oauth2:grant_type:validate_bearer&token=<<ac
cess_token>>

End Point for Client Credentials Grant Type

To obtain an access token, go to the following URL with HTTP POST and replace <<client_id>> and <<client_secret>> with appropriate
values: /POST
https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?grant_type=client_credentials&client_id=<<Client_id>>&client_secret=<<client_
secret>>

Obtain an Access Token With Grant Type as Authorization Code

Refer to https://alm.cfadevelop.net/wiki/display/CRNIDNAD/OAuth+2.0+Integration#OAuth2.0Integration-_Toc376440359

Validating an Access Token

To validate an access token, go to the following URL with HTTP POST + HTTP basic auth of a client. Replace

the <<access_token>> with the valid access token:

https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?grant_type=urn:pingidentity.com:oauth2:grant_type:validate_bearer&token=<<a
ccess_token>> .
A Success Response gives the following output:
Http status code: 200
Response body:

Token Validation Success Response

{
"scope": "",
"token_type": "urn:pingidentity.com:oauth2:validated_token",
"expires_in": 238,
"client_id": "MobileAppV1",
"access_token": {
"uid": "CFAID-Test1",
"mail": "test.user1@demo.com",
}
}

The success response also provides the client_id. This client_id refers to the client used to obtain the access token.
In case of Error:
HTTP status code: 400
Response body:

Token Validation Failure Response

{"error":"invalid_grant","error_description":"token not found, expired or
invalid"}

In case client authentication fails:

HTTP status code: 400
Response body:

Token Validation Response - In case Client authentication fails

{ "error": "invalid_client",
"error_description": "urn:pingidentity.com:oauth2:grant_type:validate_bearer
requires client authentication" }

Endpoint for Obtaining Access Token Based on Refresh Token

Access the following URL replacing <<Refresh_Token>> with the appropriate refresh token.
https://login.dev.crndev.chick-fil-a.com/as/token.oauth2?grant_type=refresh_token&refresh_token=<<REFRESH_TOKEN>>
Example: curl command is: curl \ --request POST \ --data
"grant_type=refresh_token&refresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V" \
A successful sample response looks like:

Access token based on Refresh Token Response

{ "token_type": "Bearer", "expires_in": 599, "refresh_token":
"9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d", "access_token":
"TW6kHy0TmtknIMitAvmcChT3NgDs" }

Revoking OAuth Token

Accessing the following URL provides a list OAuth tokens generated for user.
https://login.dev.crndev.chick-fil-a.com/as/oauth_access_grants.ping
Note: Authentication is required to access the page.
For REST API, access the following URL to revoke an OAuth Token.
https://login.dev.crndev.chick-fil-a.com/as/revoke_token.oauth2?token=<<refresh_token>>&client_id=<<client_id>>&token_type_hint=refresh_tok
en
Reference: http://tools.ietf.org/html/rfc7009

PingFederate: SAML Vs OpenToken

Refer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on.
#

Process

SAML

OpenToken

Step Up
Authentication

Supports Step Up Authentication

using Authentication Level
context

Does not support

Passive Login
support

Yes

No

Security

Symmetric Encryption + Digital

signatures

Symmetric Encryption

OAuth 2.0
Authentication
Level based
support

Yes

No

Is it countable
as a connection

Yes

No

If two adapters in a SAML

application is configured, it is still
counted as one connection.

But, if adapter-to-adapter mapping is performed, it is counted as connection. For

example, if the following adapter mapping is performed Facebook OpenToken and
HTMLForm Adapter OpenToken, it is counted as two.

Programmatic
Login

PingFederate and CloudHSM Integration

Perform the following steps to integrate PingFederate and CloudHSM. The integration is tested with PingFederate 7.1R2 and PingFederate 7.1R3
along with CloudHSM client 5.3.1. The following PF_HOME represents /apps/pingfederate/pingfederate_latest/pingfederate.
1. Install and configure CloudHSM client, and register with a CloudHSM partition if it is not already there. To install, follow the instructions gi
ven at.........????
2. Once CloudHSM configuration is completed, verify the Network Trust Link (NTL) by running the vtl verify command. The output looks as
shown below.
The following Luna SA Slots/Partitions were found:
Slot

Serial #

Label

156664020

qa-crnidm-mgmt

3. Copy CloudHSM client's JSP lib directory content to JAVA_HOME\jre\lib\ext if the following files libLunaAPI.so and LunaProvider.jar do
not exist.
4. Make sure that all users have execution permission on the file libLunaAPI. If required, run the following command to provide permission
to all the users:
chmod o+x

$JAVA_HOME\jre\lib\extlibLunaAPI.so

5. Add the following line to Java security providers by editing the following file $JAVA_HOME/jre/lib/security/java.security:
security.provider.10=com.safenetinc.luna.provider.LunaProvider

6. Go to the directory PF_HOME/server/default/data/ and delete JKS files if there are any.
cd /apps/pingfederate/pingfederate_latest/pingfederate/server/default/data/
rm -f *.jks

7. Edit hivemodule.xml file present in PF_HOME/server/default/data directory as shown below.

Change:
<construct class="com.pingidentity.crypto.SunJCEManager"/> to <construct class="com.pingidentity.crypto.LunaJCEManager5"/>
and
<construct class="com.pingidentity.crypto.CertificateServiceImpl"/> to <construct class="com.pingidentity.crypto.LunaCertificateServiceI
mpl5"/>
8. Edit run.properties file present in PF_HOME/bin/run.properties as shown below:
from #pf.hsm.mode=OFF to pf.hsm.mode=LUNA
9. Now, run the following commands to store the CloudHSM partition password:
Sh /apps/pingfederate/pingfederate_latest/pingfederate/bin/hsmpass.sh
Output will look like following:
PingFederate Password Changer
-------------------------------------------WARNING: Password file does not exist:
/apps/pingfederate/pingfederate-7.1.0-R3/pingfederate/bin/./../server/default/data/hsmpasswd.txt
Password: <<Enter cloudhsm partition password here>>
File hsmpasswd.txt has been created.

10. Once all the above steps are completed, restart the PingFederate server. Repeat the same for all the nodes present in cluster. Make sure
that all the nodes belong to the same CloudHSM partition.

PingFederate OAuth Vs OpenAM OAuth

The following table describes the differences between the OAuth implementation for PingFederate and OpenAM.
OpenAM
Authorization
code

/oauth2/authorize?realm=/external
Example: (HTTP POST)

https://dev.accounts.chick-fil-a.com/amserver/oauth2/authorize?realm=/external&client_id=MobileAppV1&response_type=code&scope=/sess
<<REDIRECT_URL>>
Access
token from
authorization
code

/oauth2/access_token?realm=/external
Example: (HTTP POST)

https://dev.accounts.chick-fil-a.com/amserver/oauth2/access_token?realm=/external&code=<<authorization_code>>&grant_type=authorizatio
bileAppV1&redirect_uri=<<REDIRECT_URL>>

Json payload
returned
from AS for a
uthorization
code grant
type

{
"expires_in": 719,
"token_type": "Bearer",
"refresh_token": "12af4ae9-7e07-4df3-97d3-779e8c2c8f47",
"access_token": "a26d8690-24e7-4f96-baf2-0921fd997374"
}

Access
token from
refresh token

/oauth2/access_token?realm=/external
Example: (HTTP POST)

https://dev.accounts.chick-fil-a.com/amserver/oauth2/access_token?realm=/external&grant_type=refresh_token&refresh_token=<<REFRESH
Json payload
returned
from AS for
getting
access token
in exchange
of a refresh
token

Token
validation

{
"scope": "/confirmtxns /giftcard/me /sessionid/me /user/profile",
"expires_in": 719,
"token_type": "Bearer",
"access_token": "b8984cab-b8bd-4622-b15d-f0708b73de3b"
}

/oauth2/tokeninfo
Example: HTTP GET
https://dev.accounts.chick-fil-a.com/amserver/oauth2/tokeninfo?access_token=<<Access-Token>>

Json payload
for token
validation

{
"scope": [ "/confirmtxns", "/sessionid/me", "/giftcard/me", "/user/profile" ],
"token_type": "Bearer",
"expires_in": 693,
"uid": "CFAID-BEWT6DAVE8",
"mail": "test.user1@demo.com",
"cn": "Test User1",
"realm": "/external",
"access_token": "08857e6c-69ac-4e5d-957d-e1eb04f78d23"
}

PingFederate TimeOut Values

The following table describes the timeout values for different components in PingFederate.
Component

Value

Local Login

60 minutes

Remember Me cookie

30 days

OAuth - authorization code

60 seconds

OAuth - access token

12 minutes

OAuth - Refresh Token

30 days

SocialIDM User Instructions

End Points
Environment

URL

Dev

https://my.dev.crndev.chick-fil-a.com

QA

https://my.qa.crndev.chick-fil-a.com

Production

TBD

Target URL
Name

Dev

Registration

https://my.dev.crndev.chick-fil-a.com/socialidm-web/registration

Profile
Management

https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile

Change
Password

https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile

Forgot
Password

https://my.dev.crndev.chick-fil-a.com/socialidm-web/pwdreset?goto=https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile/me

Deactivate
User
Account

https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile/deactivate

Note: These user instructions are not standard and would change as per the features added to SocialIDM.
The following modules are implemented in SocialIDM:
1.
2.
3.
4.

Registration
Profile Management
Change Password
Deactivate User Account

Important: The following links are for development environment only.

1.

Registration
Go to https://my.dev.crndev.chick-fil-a.com/socialidm-web/registration to register/create a user profile. Once the user is registered, it
automatically redirects you to the Profile Management page showing two tabs, viz. View Profile and Change Password as shown below.
Click View Profile to view your profile, and click Change Password to change your profile password.

Figure: View/Change password page

Once you click any of the tabs, you are redirected to the authentication page. Enter your credentials to log on. After successful logon, it
takes you back to the SocialIDM requested operational page. Now, you can update your profile and change password.
2.

Profile Management
On profile management page, you can view and update your profile, if required.
Go to https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile to access your profile, and is next redirected to the logon page. Enter your
credentials to view and update your profile.

3.

Change Password
Go to https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile to change your password. You are again redirected to the logon page after
accessing the profile management link. Logon takes you back to Profile management page. The Change password page appears.
Enter the current password, new password, and confirm password in the respective fields. Any mismatch of character in the New
Password and Confirm Password fields does not allow you to change your password.

4.

Deactivate User Account

Go to https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile/deactivate to deactivate your profile. There are two options, viz. 1) Back to
profile, and 2) Deactivate account.
If you click Back to profile, you are redirected to your profile.
If you click Deactivate account, the would be is deactivated.

Reset Password
A user can reset the password in two ways:

By using OTP
By answering the challenge questions and answers
Note: Only the registered and active users with a valid email can reset the password.
Go to https://my.dev.crndev.chick-fil-a.com/socialidm-web/pwdreset?goto=https://my.dev.crndev.chick-fil-a.com/socialidm-web/profile/me, the Res
et Password page opens as shown below.
1..Enter your registered email address in the Email text box, and click Search.

Figure: Resetting password

2. On successful verification of the email address, you are redirected to the Choose Reset Password Mode page. Click By One Time Passcode
if you want to reset your password using the OTP, or click By Answering Questions if you want to reset your password by answering the
challenge questions and answers.

Figure: Password reset mode

3. If you click By One Time Passcode, an OTP is sent to your mail address. The following page appears. Enter the one time passcode, account
password, and confirm the password. Click Change Password. You are redirected to the logon page with the message "Password Updated".

Figure: OTP

4. If you click By Answering Questions, the following page appears. Enter the challenge question and answer, account password, and confirm
the password. Click Change Password. You are redirected to the logon page with the message "Password Updated".

Figure: Challenge question and answer

You can log on with the reset password on the logon page.

Figure: Logon page

User Profile Integration

This section describes the end points to make REST web service calls to Directory Server through the AxWay API Server. Client can use this
interface to add, update, or authenticate a user profile. This section also describes the necessary authentication mechanism required to access
the interface.

End Points

Environment

URL

Dev

https://profile.api.dev.crndev.chick-fil-a.com

QA

https://profile.api.qa.crndev.chick-fil-a.com

Production

TBD

REST Web Services End Point URIs

User Management
Usage

Resource

Method

Add a user

/users/2.0

POST

List users based on a criteria

/users/2.0/search

POST

Get User Profile

/users/2.0/{user_id}

GET

Update Partial User Profile

/users/2.0/{user_id}

PATCH

Get one's own profile

/users/2.0/me

GET

Update one's own User Profile

/users/2.0/me

PATCH

Deactivate one's own account

/users/2.0/deactivate/me

POST

Deactivate user's account

/users/2.0/deactivate/{user_id}

POST

Link One's own Account with Social Identity

/users/<<version>>/sociallink/me

PATCH

Link user's Account with Social Identity

/users/<<version>>/sociallink/{user_id}

PATCH

Unlink One's own Account with Social Identity

/users/<<version>>/socialunlink/me

PATCH

Unlink user's Account with Social Identity

/users/<<version>>/socialunlink/{user_id}

PATCH

Credential Management
In phase -1 release, there are two types of credentials stored for a user. The first is the user's password and the other is the reset password and
challenge question-answers.
Usage

Resource

Method

Change Credentials

/credentials/1.0/{user_id}

POST

Change Own Credentials

/credentials/1.0/me

POST

List type of Credentials set for a user

/credentials/1.0/{user_id}

GET

Set/Update one's own challenge question answers

/credentials/1.0/challengeqa/{user_id}

PATCH

Validate one's own challenge question answers

/credentials/1.0/challengeqa/{user_id}

POST

Delete one's own challenge question answers

/credentials/1.0/challengeqa/{user_id}

DELETE

Obtain one's own OTP Code

/credentials/1.0/otp/{user_id}

GET

REST Web Services Security OAuth

Refer to OAuth Integration Guide for more details.

Request Payload
Refer to JSON Schema for payload.

Error Codes
The following error codes and messages are used in the integration process.

General Exception
This section describes the status codes that are shared among all the services.
Status
Code

HTTP
Code

Error Message

Comments

000

200

Successful

Call is successful.

401

401

Unauthorized

The incoming HTTP Digest Authorization header is invalid.

401

401

Unauthorized

The incoming IP Address is invalid.

400

400

Unrecognized Request

The incoming JSON payload is not in the specified format.

900

500

Datastore communication
error

The server is unable to communicate with the back end datastore.

901

500

Datastore authentication
error

The server is unable to authenticate the back end datastore.

902

500

Datastore authorization
error

The server is unable to perform the requested operation, because the service account
credential does not have sufficient privilege against the datastore.

903

500

System Error

Unhandled error scenario

904

500

Authorization Server
communication error

Unable to communicate the authorization server

905

500

Failed to load properties

from S3

Unable to initialize properties from s3

Add User
Status Code

HTTP Code

Error Message

Comments

110

500

Duplicate email address

The given email address already exists in the datastore.

111

500

Duplicate AList number

The given AList number already exists in the datastore.

114

500

Malformed Birthdate

Invalid Birth date format

115

500

Duplicate Addresses

The given address already exists in the datastore.

116

500

Duplicate phoneNumbers

The give phoneNumber already exists in the datastore

119

500

Duplicate IDP identifier

IDP identifier is already registered.

150

500

Password constraint not met.

Password constraint is not met.

190

500

Insufficient privilege

The user doesn't not have sufficient privilege to perform the operation.

199

200

Add user partial success.

Error while writing to preference store.

Get User Profile

Status Code

HTTP Code

Error Message

Comments

200

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

290

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

299

200

Get user partial success.

Error while reading from preference store.

Update User Profile

Status Code

HTTP Code

Error Message

Comments

600

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

610

500

Duplicate email address

The given email address already exists in the datastore.

611

500

Duplicate AList number

AList number is already registered.

614

500

Malformed Birthdate

Invalid Birth date format

619

500

Duplicate IDP identifier

IDP identifier is already registered.

650

500

Password constraint not met.

Password constraint is not met.

690

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

699

200

Update user partial success.

Error while writing to preference store.

List of Users Based on a Criteria

Status Code

HTTP Code

Error Message

Comments

300

200

No users found for the criteria

No users are found for the criteria.

302

500

Missing Operand1

Operand1 is missing.

303

500

Invalid Operand1

Invalid Operand1.

304

500

Missing Operand2

Operand2 is missing.

305

500

Invalid Operand1

Invalid Operand1.

306

500

Invalid Operator

Invalid Operator.

390

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

399

200

Search user partial success.

Error while querying from preference store.

Deactivate a user's account

Status Code

HTTP Code

Error Message

Comments

800

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

890

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

Link/Unlink Account with Social Identity

Status Code

HTTP Code

Error Message

Comments

900

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

901

500

Invalid Identifier

The give identifier does not exist in the datastore

990

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

Change Credentials
Status
Code

HTTP Cod
e

Error Message

Comments

3000

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

3001

500

Current password is invalid

The current password in the payload does not match the password in the
datastore.

3002

500

Password constraint not met

Password constraint is not met.

3003

500

Invalid challenge QA
credentials

Challenge questions and answers credentials are invalid.

3004

500

Invalid OTP code

OTP code is invalid.

3005

500

Invalid credential type

The provided credential type is not supported.

3090

500

Insufficient privilege

The user does not have required privileges to update the credential.

List type of Credentials Set for a User

Status Code

HTTP Code

Error Message

Comments

5000

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

5001

200

No credentials set

No credentials are set.

5090

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

Set/Update One's Own Challenge Question Answers

Status Code

HTTP Code

Error Message

Comments

6000

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

6090

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

Validate One's Own Challenge Question Answers

Status
Code

HTTP Cod
e

Error Message

Comments

7000

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

7001

500

Invalid Challenge Question

Answers

The provided answers do not match the answers stored in the datastore.

7090

500

Insufficient privilege

The user does not not have the required privileges to perform the
operation.

Delete One's Own Challenge Question Answers

Status
Code

HTTP Cod
e

Error Message

Comments

8000

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

8001

500

Challenge Question Answers does not

exist.

The provided challenge question answers do not exist in the

datastore.

8090

500

Insufficient privilege

The user does not not have the required privileges to perform the
operation.

Obtain One's Own OTP Code

Status Code

HTTP Code

Error Message

Comments

9000

500

Invalid CFA-UID

The given CFA-UID does not exist in the datastore.

9090

500

Insufficient privilege

The user does not not have the required privileges to perform the operation.

API
Version=v3

User Management
Usage

Resource

Method

Scope

Add a user

/users/<<version>>

POST

/users

List users based on a criteria

/users/<<version>>/search

POST

/users

Get User Profile

/users/<<version>>/{user_id}

GET

/users

Update Partial User Profile

/users/<<version>>/{user_id}

PATCH

/users

List groups for a specified user

/users/<<version>>/{user_id}/groups

GET

/users

Get one's own profile

/users/<<version>>/me

GET

/users/me, /users

Get one's group association

/users/<<version>>/me/groups

GET

/users/me, /users

Update one's own User Profile

/users/<<version>>/me

PATCH

/users/me, /users

Deactivate user's account

/users/<<version>>/deactivate/{user_id}

POST

/users

Deactivate One's own account

/users/<<version>>/deactivate/me

POST

/users/me, /users

Link One's own Account with Social Identity

/users/<<version>>/sociallink/me

PATCH

/users/me, /users

Link Account with Social Identity

/users/<<version>>/sociallink/{user_id}

PATCH

/users

Unlink One's own Account with Social Identity

/users/<<version>>/socialunlink/me

PATCH

/users/me, /users

Unlink Account with Social Identity

/users/<<version>>/socialunlink/{user_id}

PATCH

/users

Group Management
Usage

Resource

Method

Add a group

/groups/<<version>>

POST

List groups based on a criteria

/groups/<<version>>

GET

Get Group Information

/groups/<<version>>/{group_id}

GET

Update Partial Group Parameters

/groups/<<version>>/{group_id}

PATCH

List the users in a specified group

/groups/<<version>>/?{group_id}?/users

GET

Add a user to a specified group

/groups/<<version>>/?{group_id}?/users/?{user_id}?

PUT

Remove a user from a group

/groups/<<version>>/?{group_id}?/users/?{user_id}?

DELETE

Validate that a user is in a group.

/groups/<<version>>/?{group_id}?/users/?{user_id}?

HEAD

Credential Management
In phase -1 release, there are two types of credentials stored for a use. First being user's password and other being password reset challenge
question answers.
Usage

Resource

Method

Scope

Change Credentials

/credentials/<<version>>/{user_id}

POST

/credentials

Change Own Credentials

/credentials/<<version>>/me

POST

/credentials/me

List type of Credentials set for a user

/credentials/<<version>>/{user_id}

GET

/credentials

Set/Update one's own challenge question answers

/credentials/<<version>>/challengeqa

PATCH

/credentials

Validate one's own challenge question answers

/credentials/<<version>>/challengeqa

POST

/credentials

Delete one's own challenge question answers

/credentials/<<version>>/challengeqa

DELETE

/credentials

Obtain one's own OTP Code

/credentials/<<version>>/otp/{user_id}

GET

/credentials

Get challenge questions

/credentials/<<version>>/challengeqa/{lang}

GET

/credentials

User Profile Management APIs

Add User Profile
This section defines the APIs available for Adding a user.

User Management API: Add a user

Usage

Resource

Method

Add a user

/users/<<version>>

POST

Sample User Profile Creation

Add a User
Request
POST:/users/2.0
SampleAddUpdateUser.json

Response
{
"statusCode": "000",
"statusMessage": "success",
"uid": "CFAID-Z3FTVS5CS7FL6309"
}

Get User Profile

This section defines the APIs available for getting a user.

User Management API: Get a user

Usage

Resource

Method

Get a user profile

/users/<<version>>/{user_id}

GET

Get one's own profile

/users/<<version>>/me

GET

Sample User Profile Retrival

Get a User
Request
GET:/users/2.0/CFAID-ABCDEFGHIJ123456

Response

{
"statusCode": "000",
"statusMessage": "success",
"userProfile":
{
"uid": "CFAID-Z3FTVS5CS7FL6309",
"socialConnections":
[
{
"idp": "google",
"identifier": "sample.user"
},
{
"idp": "facebook",
"identifier": "sample.user"
}
],
"name":
{
"familyName": "Sample",
"givenName": "User",
"displayName": "Sample User"
},
"phoneNumbers":
[
{
"value": "+1 98989898989",
"type": "Mobile"
},
{
"value": "+1 6767676767",
"type": "Home"
}
],
"emails":
[
{
"primary": true,
"value": "sample.user@gmail.com"
},
{
"primary": false,
"value": "sample.user@yahoo.com"
}
],
"systemAttributes": [],
"extendedAttributes":
[
{"termsOfUse": "true"},
{"ageRange": "25-30"}
],
"addresses": []
}
}

Get one's own profile

Request
GET:/users/2.0/me

Response
{
"statusCode": "000",
"statusMessage": "success",
"userProfile":
{
"uid": "CFAID-Z3FTVS5CS7FL6309",
"socialConnections":
[
{
"idp": "google",
"identifier": "sample.user"
},
{
"idp": "facebook",
"identifier": "sample.user"
}
],
"name":
{
"familyName": "Sample",
"givenName": "User",
"displayName": "Sample User"
},
"phoneNumbers":
[
{
"value": "+1 98989898989",
"type": "Mobile"
},
{
"value": "+1 6767676767",
"type": "Home"
}
],
"emails":
[
{
"primary": true,
"value": "sample.user@gmail.com"
},
{
"primary": false,
"value": "sample.user@yahoo.com"
}
],
"systemAttributes": [],
"extendedAttributes":
[
{"termsOfUse": "true"},
{"ageRange": "25-30"}
],
"addresses": []
}
}

Update User Profile

This section defines the APIs available for updating a user.

User Management API: Update a user

Usage

Resource

Method

Update a user

/users/<<version>>/{user_id}

PATCH

Update one's own profile

/users/<<version>>/me

PATCH

Sample User Profile Update

Update a User
Request
PATCH:/users/2.0/CFAID-ABCDEFGHIJ123456
SampleAddUpdateUser.json

Response
{
"statusCode": "000",
"statusMessage": "success"
}

Update one's own profile

Request
PATCH:/users/2.0/me
SampleAddUpdateUser.json

Response
{
"statusCode": "000",
"statusMessage": "success"
}

Search Users
This section defines the APIs available for search users.

User Management API: Add a user

Usage

Resource

Method

Search users

/users/<<version>>/search

POST

Supported Logical Operator

Operator Syntax

Description

AND

All condition must be met.

OR

One of the conditions must be met.

NOT

Any entries that doesn't meet the condition.

Supported Operator
Operator Syntax

Description

EQ

The two operands must be equal

GE

The result must be great than or equal to operand2.

LE

The result must be less than or equal to operand2.

APPROX

The result must be approximately equal to operand2.

Sample User Profile Search

Search Users based on given name AND display name
The below example uses the logical operator AND. It will search for givenName="TK" AND displayName startsWith "TK". * is a wildcard symbol
that allows starts with search.

Request
POST:/users/2.0/search

{
"logicalOperator":"AND",
"operands":[
{
"operator":"EQ",
"operand1":"givenName",
"operand2":"TK"
},
{
"operator":"EQ",
"operand1":"displayName",
"operand2":"TK*"
}
]
}

Response

{
"statusCode":
[
"000",
"success"
],
"searchResultSize": 12,
"searchResult":
[
{
"uid": "CFAID-TKTesting1",
"socialConnections": [],
"name":
{
"familyName": "CHIN",
"givenName": "TK",
"displayName": "TK Chin"
},
"phoneNumbers": [],
"emails": [],
"systemAttributes": [],
"extendedAttributes": [],
"addresses": []
},
{
"uid": "CFAID-TKTesting2",
......
},
{
"uid": "CFAID-TKTesting3",
......
},
......
]
}

Search Users based on given name OR email

The below example uses the logical operator OR. It will search for givenName="TK" OR email="than-khar.chin@quberasolutions.com".

Request
POST:/users/2.0/search

{
"logicalOperator":"OR",
"operands":[
{
"operator":"EQ",
"operand1":"givenName",
"operand2":"TK"
},
{
"operator":"EQ",
"operand1":"email",
"operand2":"than-khar.chin@quberasolutions.com"
}
]
}

Response
{
"statusCode":
[
"000",
"success"
],
"searchResultSize": 2,
"searchResult":
[
{
"uid": "CFAID-TKTesting1",
"socialConnections": [],
"name":
{
"familyName": "CHIN",
"givenName": "TK",
"displayName": "TK Chin"
},
"phoneNumbers": [],
"emails": [],
"systemAttributes": [],
"extendedAttributes": [],
"addresses": []
},
{
"uid": "CFAID-TKTesting2",
......
},
{
"uid": "CFAID-TKTesting3",
......
},
......
]
}

Deactivate an account
This section defines the APIs available for deactivating a user.

User Management API: Get a user

Usage

Resource

Method

Deactivate a user profile

/users/<<version>>/deactivate/{user_id}

POST

Deactivate one's own profile

/users/<<version>>/deactivate/me

POST

Sample User Profile Deactivation

Deactivate a User
Request
POST:/users/2.0/deactivate/CFAID-ABCDEFGHIJ123456

Response
{
"statusCode": "000",
"statusMessage": "success"
}

Deactivate one's own profile

Request
POST:/users/2.0/deactivate/me

Response
{
"statusCode": "000",
"statusMessage": "success"
}

Link/Unlink Account

Credential Management APIs

Refer to the following sections that describe the usage of the Credential Management APIs.
Credential Management: Admin Password Reset
Credential Management: Change Password
Credential Management: KBA
Credential Management: OTP
Credential Management: Get Credential

Credential Management: Admin Password Reset

This section defines the APIs available for Admin password reset.

Credential Management API: Admin Password Reset

Usage

Resource

Method

Change Credentials

/credentials/<<version>>/{user_id}

POST

Sample Password Reset Call

Change Credentials - Admin Password Reset
Note: This API only works if the user has not set the password yet.

Request
POST:/credentials/1.0/{user_id}

{
"type": "Password",
"fields": [{
"fieldName":"password",
"fieldValue":"SecretPassword"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Credential Management: Change Password

This section defines the APIs available for Change Password.

Credential Management API - Change Password

Usage

Resource

Method

Change credentials

/credentials/<<version>>/{user_id}

POST

Change own credentials

/credentials/<<version>>/me

POST

Change Credentials: Password Change

Request
POST:/credentials/1.0/{user_id}

{
"type": "Password",
"fields": [{
"fieldName":"currentPassword",
"fieldValue":"OldSecretPassword"
},
{
"fieldName":"newPassword",
"fieldValue":"SecretPassword"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Change Own Credentials: Password Change

Request
POST:/credentials/1.0/me

{
"type": "Password",
"fields": [{
"fieldName":"currentPassword",
"fieldValue":"OldSecretPassword"
},
{
"fieldName":"newPassword",
"fieldValue":"SecretPassword"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Credential Management: Get Credential

This section defines the APIs available for Get Credentials.
Note: The API neither displays the actual KBA nor the password, but it only serves as a mechanism to display what is set.

Credential Management API: Get Credentials

Usage

Resource

Method

List type of credentials set for a user

/credentials/<<version>>/{user_id}

GET

Sample Password Reset Call

List Type of Credentials Set for a User: Password Only
The following output is displayed only if the password is set. The actual password is never displayed.

Request
GET:/credentials/1.0/{user_id}

Response

[{
"type": "Password",
"fields": [{
"fieldName":"newPassword",
"fieldValue":"xxxxxxxxxx"
}]
}]

List Type of Credentials Set for a User: Password and KBA

The following output is displayed only if the password and KBA are set.

Request
GET:/credentials/1.0/{user_id}

Response
[{
"type": "Password",
"fields": [{
"fieldName":"currentPassword",
"fieldValue":"xxxxxxxxxx"
}]
},
{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"xxxxxxxxxx"
},
{
"fieldName":"03",
"fieldValue":"xxxxxxxxxx"
}]
}]

List Type of Credentials Set for a User: KBA Only

The following output is displayed if the password and KBA are set.

Request
GET:/credentials/1.0/{user_id}

Response

[{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"xxxxxxxxxx"
},
{
"fieldName":"03",
"fieldValue":"xxxxxxxxxx"
}]
}]

Credential Management: KBA

This section defines the APIs available for KBA Password Reset.

Credential Management API: KBA

Usage

Resource

Method

Change Credentials

/credentials/<<version>>/{user_id}

POST

Change Own Credentials

/credentials/<<version>>/me

POST

Set/Update one's own challenge question answers

/credentials/<<version>>/challengeqa/{user_id}

PATCH

Validate one's own challenge question answers

/credentials/<<version>>/challengeqa/{user_id}

POST

Delete one's own challenge question answers

/credentials/<<version>>/challengeqa/{user_id}

DELETE

Get challenge questions

/credentials/<<version>>/challengeqa/{lang}

GET

Data Format for KBA Store in Directory

Each KBA answer is stored in the following format in the directory attribute.
AuthStore_KBA_Schema.json

Sample KBA Calls

Change Credentials: KBA
Request
POST:/credentials/1.0/{user_id}

{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"My Answer to 01"
},
{
"fieldName":"02",
"fieldValue":"My Answer to 02"
},
{
"fieldName":"newPassword",
"fieldValue":"SecretPassword"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Change Own Credentials: KBA

Request
POST:/credentials/1.0/me

{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"My Answer to 01"
},
{
"fieldName":"02",
"fieldValue":"My Answer to 02"
},
{
"fieldName":"newPassword",
"fieldValue":"SecretPassword"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Set/Update One's Own Challenge Question Answers

Request
PATCH:/credentials/<<version>>/challengeqa/{user_id}

{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"My Answer to 01"
},
{
"fieldName":"02",
"fieldValue":"My Answer to 02"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Validate One's Own Challenge Question Answers

Request
POST:/credentials/<<version>>/challengeqa/{user_id}

{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"My Answer to 01"
},
{
"fieldName":"02",
"fieldValue":"My Answer to 02"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Delete One's Own Challenge Question Answers

Request
DELETE:/credentials/<<version>>/challengeqa/{user_id}

{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01"
},
{
"fieldName":"02"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Get Challenge Questions

Request
GET:/credentials/<<version>>/challengeqa/{lang}

Response
{
"statusCode": "000",
"statusMessage": "success",
"credentials": {
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
"fieldValue":"What is your mother's maiden name?"
},
{
"fieldName":"02",
"fieldValue":"Where is your city of birth?"
},
{
"fieldName":"03",
"fieldValue":"What's your favorite food?"
}]
}
}

Credential Management: OTP

This section defines the APIs available for OTP.

Credential Management API: OTP

Usage

Resource

Method

Obtain one's own OTP Code

/credentials/<<version>>/otp/{user_id}

GET

Sample OTP Calls

Change Credentials: OTP
Request
POST:/credentials/1.0/{user_id}

{
"type": "OTP",
"fields": [{
"fieldName":"OTP_CODE",
"fieldValue":"123456"
},
{
"fieldName":"newPassword",
"fieldValue":"SecretPassword"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

Obtain One's Own OTP Code

Request
GET:/credentials/1.0/otp/{user_id}

Response
{
"statusCode": "000",
"statusMessage": "success",
"credentials": {
"type": "OTP",
"fields": [{
"fieldName": "OTP_CODE",
"fieldValue": "793458"
}]
}
}

Validate One's Own OTP Code

Request

POST:/credentials/1.0/otp/{user_id}

{
"type": "OTP",
"fields": [{
"fieldName":"OTP_Code",
"fieldValue":"123456"
}]
}

Response
{
"statusCode":"000",
"statusMessage":"success"
}

JSON Schema
The following schemas are used for request and response payload.
User Profile: UserProfile.json
Credential: Credentials.json
Search Query: SearchQuery.json
Note that these schemas are for single object payload only. When there is a need to use a multi-valued object, an array of the above mentioned
schemas are used.
Go to Sample JSON Payload to look at the sample JSON payload.

JSON Schema and Authentication Store Attribute Mapping

JSON Group

Authentication Store

JSON Attribute Name

uid

uid

uid

name

givenName

givenName

cn

displayName

sn

familyName

primaryEmail

emails.primary = true

mail

emails

telephoneNumber

Work

mobile

Mobile

homePhone

Home

emails

phoneNumbers

addresses

postalAddress, zip, city, country

addresses.type = Home

socialConnections

externalUID

idp, identifier

systemAttributes

regComplete

regComplete

emailVerified

emailVerified

nonVerifiedEmail

nonVerifiedEmail

extendedAttributes

source

source

aListCardNumber

aListCardNumber

aListHomeStore

aListHomeStore

JSON Schema and Preference Store Attribute Mapping

JSON Group

Preference Store Attributes

JSON Schema Attribute

addresses

billingAddress

addresses.type=Billing

shippingAddress

addresses.type=Shipping

preferredStoreLocation

preferredStoreLocation

preferredFood

preferredFood

preferredBeverage

preferredBeverage

favoriteRestaurant

favoriteRestaurant

mobileAppPush

mobileAppPush

userPreferences

userPreferences

termsOfUse

termsOfUse

profileURL

profileURL

photoURL

photoURL

maritalStatus

maritalStatus

incomeRange

incomeRange

ageRange

ageRange

cfaAgeRangeEffectiveDate

cfaAgeRangeEffectiveDate

birthDate

dateOfBirth

emailOptIn

emailOptIn

smsOptIn

smsOptIn

extendedAttributes

Sample JSON Payloads

The following are the sample JSON payloads:
SampleAddUpdateUser.json
SampleSearchQuery.json