API Documentation

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
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
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>>

{
"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",
}
}
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" \

{ "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
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,
"refresh_token": "12af4ae9-7e07-4df3-97d3-779e8c2c8f47",
"access_token": "a26d8690-24e7-4f96-baf2-0921fd997374"
}
Access
token from
refresh token
/oauth2/access_token?realm=/external
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,
"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" ],
"expires_in": 693,
"uid": "CFAID-BEWT6DAVE8",
"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
POST
Delete one's own challenge question answers
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
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
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.
690
500
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
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
890
500
Link/Unlink Account with Social Identity

Status Code
HTTP Code
Error Message
Comments
900
500
Invalid CFA-UID
901
500
Invalid Identifier
The give identifier does not exist in the datastore
990
500
Change Credentials
Status
Code
HTTP Cod
e
Error Message
Comments
3000
500
Invalid CFA-UID
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
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
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
5001
200
No credentials set
No credentials are set.
5090
500
Set/Update One's Own Challenge Question Answers

Status Code
HTTP Code
Error Message
Comments
6000
500
Invalid CFA-UID
6090
500
Validate One's Own Challenge Question Answers

Status
Code
HTTP Cod
e
Error Message
Comments
7000
500
Invalid CFA-UID
7001
500
Invalid Challenge Question

Answers
The provided answers do not match the answers stored in the datastore.
7090
500
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
8001
500
Challenge Question Answers does not

exist.
The provided challenge question answers do not exist in the

datastore.
8090
500
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
9090
500
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
PATCH
/users
List groups for a specified user
/users/<<version>>/{user_id}/groups
GET
/users
/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
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
DELETE
Validate that a user is in a group.
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
/credentials/<<version>>/me
POST
/credentials/me
List type of Credentials set for a user
GET
/credentials
/credentials/<<version>>/challengeqa
PATCH
/credentials
POST
/credentials
DELETE
/credentials
/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
GET
GET
Sample User Profile Retrival

Get a User
Request
GET:/users/2.0/CFAID-ABCDEFGHIJ123456
Response
{
"userProfile":
{
"uid": "CFAID-Z3FTVS5CS7FL6309",
"socialConnections":
[
{
"idp": "google",
"identifier": "sample.user"
},
{
"idp": "facebook",
}
],
"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": []
}
}

Request
GET:/users/2.0/me
Response
{
"userProfile":
{
"uid": "CFAID-Z3FTVS5CS7FL6309",
"socialConnections":
[
{
"idp": "google",
},
{
"idp": "facebook",
}
],
"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"
}
],
"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
PATCH
Update one's own profile
PATCH
Sample User Profile Update

Update a User
Request
PATCH:/users/2.0/CFAID-ABCDEFGHIJ123456
Response
{
"statusMessage": "success"
}
Update one's own profile

Request
PATCH:/users/2.0/me
Response
{
}
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": [],
"extendedAttributes": [],
"addresses": []
},
{
......
},
{
......
},
......
]
}
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":
[
{
"socialConnections": [],
"name":
{
"familyName": "CHIN",
"givenName": "TK",
"displayName": "TK Chin"
},
"phoneNumbers": [],
"emails": [],
"extendedAttributes": [],
"addresses": []
},
{
......
},
{
......
},
......
]
}
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
{
}
Deactivate one's own profile

Request
POST:/users/2.0/deactivate/me
Response
{
}
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
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
POST
Change own credentials
POST
Change Credentials: Password Change

Request
{
"type": "Password",
"fields": [{
"fieldName":"currentPassword",
"fieldValue":"OldSecretPassword"
},
{
"fieldName":"newPassword",
}]
}
Response
{
"statusCode":"000",
}
Change Own Credentials: Password Change

Request
POST:/credentials/1.0/me
{
"type": "Password",
"fields": [{
"fieldValue":"OldSecretPassword"
},
{
}]
}
Response
{
"statusCode":"000",
}
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
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": [{
"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
Response
[{
"type": "Password",
"fields": [{
}]
},
{
"type": "Challenge Q&A",
"fields": [{
"fieldName":"01",
},
{
"fieldName":"03",
}]
}]
List Type of Credentials Set for a User: KBA Only

The following output is displayed if the password and KBA are set.
Request
Response
[{
"fields": [{
"fieldName":"01",
},
{
"fieldName":"03",
}]
}]
Credential Management: KBA

This section defines the APIs available for KBA Password Reset.
Credential Management API: KBA

Usage
Resource
Method
Change Credentials
POST
POST
/credentials/<<version>>/challengeqa/{user_id}
PATCH
POST
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
{
"fields": [{
"fieldName":"01",
"fieldValue":"My Answer to 01"
},
{
"fieldName":"02",
},
{
}]
}
Response
{
"statusCode":"000",
}
Change Own Credentials: KBA

Request
POST:/credentials/1.0/me
{
"fields": [{
"fieldName":"01",
},
{
"fieldName":"02",
},
{
}]
}
Response
{
"statusCode":"000",
}
Set/Update One's Own Challenge Question Answers

Request
PATCH:/credentials/<<version>>/challengeqa/{user_id}
{
"fields": [{
"fieldName":"01",
},
{
"fieldName":"02",
}]
}
Response
{
"statusCode":"000",
}
Validate One's Own Challenge Question Answers

Request
POST:/credentials/<<version>>/challengeqa/{user_id}
{
"fields": [{
"fieldName":"01",
},
{
"fieldName":"02",
}]
}
Response
{
"statusCode":"000",
}
Delete One's Own Challenge Question Answers
Request
DELETE:/credentials/<<version>>/challengeqa/{user_id}
{
"fields": [{
"fieldName":"01"
},
{
"fieldName":"02"
}]
}
Response
{
"statusCode":"000",
}
Get Challenge Questions

Request
GET:/credentials/<<version>>/challengeqa/{lang}
Response
{
"credentials": {
"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
/credentials/<<version>>/otp/{user_id}
GET
Sample OTP Calls

Change Credentials: OTP
Request
{
"type": "OTP",
"fields": [{
"fieldName":"OTP_CODE",
"fieldValue":"123456"
},
{
}]
}
Response
{
"statusCode":"000",
}
Obtain One's Own OTP Code

Request
GET:/credentials/1.0/otp/{user_id}
Response
{
"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",
}
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:
SampleSearchQuery.json

API Documentation

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

API Documentation

Uploaded by

Copyright:

Available Formats

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

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

Granting temporary access to public server for SCP

Install rssh package on host

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

Process to grant access

Public IP for OpenVPN

OAuth 2.0 Clients

Grant Types Supported

Resource owner password credentials Grant type

Resource owner password credentials Grant type

NCR Mobile Ordering Mobile App

NCR Mobile Ordering Resource Server

Chick-fil-A Flag Ship Mobile App

Chick-fil-A Testing Team

Resource owner password credentials Grant type

OAuth 2.0 Integration

OAuth 2.0 Clients

OAuth 2.0 Development Tools

Chrome REST Client

Firefox REST Client

Figure 1: Integration process

Integration With OAuth Authorization Server

OAuth 2.0 End-Points

Used by the client to validate an access token.

Getting token information

Authorization code grant

OAuth 2.0 Authorization Grant

Figure 2: Authorization code grant sequence

Scopes Within the Solution

User Attributes Accessible

Integration With OAuth Resource Server

Including OAuth Access Token (REST Web Services)

Bearer <<OAuth Access Token>>

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

Using Refresh Token

Figure 3: Refreshing an expired access token

Sample Use Cases and Screenshots

End-Point URL to Authorize

Figure 4: Sequence for obtaining the access and refresh tokens

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

Figure 5: Logon page

Enter the username and password.

Figure 6: Entering user credentials

End-Point URL to Access an Access Token

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

Endpoint for Obtaining Access Toke Based on Refresh Token

Access token based on Refresh Token Response

Getting Token info

A successful sample response looks like:

Access token based on Refresh Token Response

OAuth 2.0 Integration Endpoints, Sample Requests, and Sample

Endpoint for Resouce Owner Password Crendetials Grant Type

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

End Point for Client Credentials Grant Type

Obtain an Access Token With Grant Type as Authorization Code

Validating an Access Token

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

Token Validation Success Response

Token Validation Failure Response

In case client authentication fails:

Token Validation Response - In case Client authentication fails

Endpoint for Obtaining Access Token Based on Refresh Token

Access token based on Refresh Token Response