Configuring SafeID Challenge in Oracle Advanced Authentication
Introduction
This tutorial shows Administrators how to configure the SafeID challenge factor for a user in Oracle Advanced Authentication (OAA) for the purposes of multi-factor authentication.
SafeID/Classic tokens generate a Time-based One Time Passcode (TOTP) every 60 seconds:
Description of the illustration safeidclassic.jpg
Due to the nature of SafeID it is not possible for users to add SafeID using the Self-Service Portal, hence it must be configured by an Administrator using REST API’s.
Note: Only SafeID/Classic keyfobs are supported for use with Oracle Advanced Authentication. For more information on SafeID/Classic, see SafeID Hardware Tokens.
Objectives
In this tutorial you will perform the following tasks:
- Configure the SafeID challenge factor for a user using REST API’s.
Prerequisites
Before starting this tutorial ensure you have met these requirements:
- An Oracle Advanced Authentication deployment is available.
- You know the
<OAAService>URL and associated username and password. For details on how to find this information, see Printing Deployment Details. - The end user has access to the Self-Service Portal and can login with their credentials.
- The end user has been given a SafeID/Classic keyfob.
- You have the secret key associated with the serial number of the SafeID/Classic keyfob.
Configure SafeID Keys for a User Using REST API’s
- When SafeID is configured for a user it is added as an
Oracle Mobile Authenticator(OMA) factor. To check if the user has any existing OMA factors enabled, run the following curl command:
curl --location '<OAAService>/oaa/runtime/preferences/v1?userId=<user>&groupId=<group>' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>'
For example:
curl --location 'https://oaa.example.com/oaa/runtime/preferences/v1?userId=testuser&groupId=Default' \
--header 'Authorization: Basic b2FhaW5zdGFsbC1vYWE6YXBpa2V5dG9iZXVzZWRkdXJpbmdpbnN0YWxsYXRpb24='
If the user has an existing OMA factor (or factors) it will be shown as follows:
{
"userId": "testuser",
"groupId": "default",
"uniqueUserId": "5b69e952-edc7-44ca-b52a-4c1221a233a9",
"factorsRegistered": [
{
"isPreferred": false,
"factorName": "Oracle Mobile Authenticator",
"factorKey": "ChallengeOMATOTP",
"factorAttributes": [
{
"factorAttributeName": "omatotpsecretkey",
"factorAttributeValue": [
{
"value": "mysecretkey",
"isPreferred": false,
"isVerified": true,
"isValidated": true,
"name": "My Oracle Mobile Authenticator",
"isEnabled": true,
"createTime": {
"parseFailed": false,
"rawParam": "<DATE>",
"dateTime": "<DATE>"
}
}
]
}
]
}
]
}
If any OMA factors are returned, you must note down the value and name for each OMA factor. In the above example one OMA factor exists with "value": "mysecretkey" and "name": "My Oracle Mobile Authenticator".
- To register the SafeID factor for the user, run the following curl command:
curl --location --request PUT '<OAAService>/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
"userId": "<userId>",
"groupId": "<groupId>",
"factorsRegistered": [
{
"factorAttributes": [
{
"factorAttributeValue": [
{
"value": "<secretKey>",
"name": "safeID TOTP",
"isEnabled": true
},
{
"value": "<existingSecretKey1>",
"name": "<existingOMAFactorName1>",
"isEnabled": true
},
{
"value": "<existingSecretKey2>",
"name": "<existingOMAFactorName2>",
isEnabled": true
},
],
"factorAttributeName": "omatotpsecretkey"
}
],
"factorKey": "ChallengeOMATOTP",
"isPreferred": false
}
]
}'
where:
<OAAService>is the<OAAService>URL.<userId>is the username for whom you want to add the SafeID factor.<groupId>is the group that the user belongs.<secretKey>is the secret key associated with the serial number of the SafeID/Classic keyfob.<existingSecretKeyX>is the secret key for the existing factor.<existingOMAFactorNameX>is the factor name for the existing factor.
For example:
curl --location --request PUT 'https://oaa.example.com/oaa/runtime/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic b2FhaW5zdGFsbC1vYWE6YXBpa2V5dG9iZXVzZWRkdXJpbmdpbnN0YWxsYXRpb24=' \
--data '{
"userId": "testuser",
"groupId": "Default",
"factorsRegistered": [
{
"factorAttributes": [
{
"factorAttributeValue": [
{
"value": "XYXYXYXYXYXYYXYXYXYXYXYXY",
"name": "safeID TOTP",
"isEnabled": true
},
{
"value": "mysecretkey",
"name": "My Oracle Mobile Authenticator",
"isEnabled": true
}
],
"factorAttributeName": "omatotpsecretkey"
}
],
"factorKey": "ChallengeOMATOTP",
"isPreferred": false
}
]
}'
Note: The factorAttributeValue section should contain the new SafeID factor to be added and any existing OMA factors. Failure to add the existing OMA factors will lead to those factors being overwritten by the SafeID factor. If no existing OMA factors exist then the entry should be:
"factorAttributes": [
{
"factorAttributeValue": [
{
"value": "XYXYXYXYXYXYYXYXYXYXYXYXY",
"name": "safeID TOTP",
"isEnabled": true
}
],
"factorAttributeName": "omatotpsecretkey"
}
]
...
If successful you will see the following response:
{
"preferences": {
"userId": "testuser",
"groupId": "default",
"uniqueUserId": "5b69e952-edc7-44ca-b52a-4c1221a233a9",
"factorsRegistered": [
{
"isPreferred": false,
"factorName": "Oracle Mobile Authenticator",
"factorKey": "ChallengeOMATOTP",
"factorAttributes": [
{
"factorAttributeName": "omatotpsecretkey",
"factorAttributeValue": [
{
"value": "XYXYXYXYXYXYYXYXYXYXYXYXY",
"isPreferred": false,
"isVerified": true,
"isValidated": true,
"name": "safeID TOTP",
"isEnabled": true,
"createTime": {
"parseFailed": false,
"rawParam": "<DATE>",
"dateTime": "<DATE>"
}
},
{
"value": "mysecretkey",
"isPreferred": false,
"isVerified": true,
"isValidated": true,
"name": "My Oracle Mobile Authenticator",
"isEnabled": true,
"createTime": {
"parseFailed": false,
"rawParam": "<DATE>",
"dateTime": "<DATE>"
}
}
]
}
]
}
]
},
"message": {
"responseCode": "200",
"responseMessage": "User Preferences updated."
}
}
View the Factor in the Self-Service Portal
Once the factor is registered, the end user will be able to see the factors in the Self-Service Portal.
-
Access the Self-Service Portal. For example,
https://oaa.example.com/oaa/rui. -
Enter your user credentials. For example,
testuser/<password>. -
In the left navigation menu, select My Authenticators.
-
The SafeID factor will be shown as follows:
Learn More
- To learn how to use factors with Windows device authentication and Oracle Universal Authenticator, see Configuring Device Authentication on Windows Using Oracle Access Management and Multi-Factor Authentication.
- To learn how to use factors when accessing an OAM protected application with MFA, see Integrate Oracle Access Management with Oracle Advanced Authentication.
Feedback
To provide feedback on this tutorial, please contact idm_user_assistance_ww_grp@oracle.com
Acknowledgements
- Author - Russ Hodgson
More Learning Resources
Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.
For product documentation, visit Oracle Help Center.
Configuring SafeID Challenge in Oracle Advanced Authentication
F99913-01
June 2024