OATH Web Service

Description Manages OATH information.
Namespace http://portwise.com/ws/v1/oath
Endpoint https://<hostname>/ws/v1/services/OATH
Style Document/Literal
WSDL https://<host>/ws/v1/services/OATH?wsdl
Since 5.2
See also User Account

Manages the OATH settings on a user account i.e. gives possibility to list the providers imported in the system, and to manage the OATH properties on a user account. The OATH services requires that the supplied subject belongs to a role that has been granted user account administrator and/or helpdesk privileges and that the accounts being administrered is assigned to that role. Note that any text refering to a user account is a Smart ID Digital Access user account.

Endpoint Services


Name getOATHProperties
Description Gets the OATH properties for a certain user account. Used to fetch user account OATH settings for editing.
Input
subject a Subject representing the entity fetching the OATHProperties.
username a string with the identity of a user account.
Output an OATHProperties object with the OATH settings for the specified user acount.
Since 5.2
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name getOCRAProperties
Description Gets the OCRA properties for a certain user account. Used to fetch user account OCRA settings for editing.
Input
subject a Subject representing the entity fetching the OCRAProperties.
username a string with the identity of a user account.
Output an OCRAProperties object with the OCRA settings for the specified user acount.
Since 5.3
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name getProviders
Description Gets list of providers imported in Smart ID Digital Access. These providers are meant to be used when adding tokens to a user.
Input
subject a Subject representing the entity fetching Providers.
Output List<Providers> with all providers available in the system.
Since 5.2
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name initOATHToken
Description In order to re-synchronize a token, the user needs to run this initialization method to get a challenge (which the resynchOCRAToken method requires).
Input
subject a Subject representing the entity which performs the initialization method.
username a String representing the username.
oathToken a OCRAToken representing the token to re-synchronize.
Output an OATHResynchData object containing a challenge and counter window settings.
Since 5.3
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name updateOATHProperties
Description Updates the OATH Settings for a user. The user account is specified in the OATHProperties when fetching properties.
Input
subject a Subject representing the entity performing the update of the OATHProperties.
oathProperties OATHProperties representing the new state of the associated user account.
Output  
Since 5.2
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name updateOCRAProperties
Description Updates the OCRASettings for a user. The user account is specified in the OCRAProperties when fetching properties.
Input
subject a Subject representing the entity performing the update of the OCRAProperties.
ocraProperties OCRAProperties representing the new state of the associated user account.
Output  
Since 5.3
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.


Name provisionNewOATHProfile
Description Adds new Token and returns activation information. The user account is specified in the OATHProperties when fetching properties.
Input
subject a Subject representing the entity performing the update of the OATHProperties.
oathProperties OATHProperties representing the new state of the associated user account.
Output A List<MapItem> containing any notification messages or null if none was available.
Since 5.12
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name renameProvider
Description Rename an existing provider, returns true if successful. This method stores the new provider name in the database.
Input
subject a Subject representing the entity performing the renaming.
newProviderName String object with new provider name.
provider Provider representing the provider to rename.
Output True if successful, otherwise false.
Since 5.3
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name resynchOATHToken
Description Re-synchronizes the OATH token for a user. The user account owning the token is specified in the username input.
Input
subject a Subject representing the entity performing the re-synchronization of the OATH token.
username a string identifying the user account owning the OATH token.
oathToken a OATHToken representing the OATH token.
otp1 a string with the the first OTP.
otp2 a string with the second sequential OTP.
Output  
Since 5.2
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Name resynchOCRAToken
Description Re-synchronizes the OCRA token for a user. The user account owning the token is specified in the username input.
Input
subject a Subject representing the entity performing the re-synchronization of the OCRA token.
username a string identifying the user account owning the OATH token.
ocraToken a OCRAToken representing the OCRA token.
resynchData an OATHResynchData object containing a challenge (generated by first calling initOATHToken method) and counter window settings.
otp1 a string with the the first OTP.
otp2 a string with the second sequential OTP.
Output  
Since 5.2
Faults
WSException if a general error occurs.
OATHException if OATH operation fails.

Java Example

The example shows how to add a token and enable OATH on a user account. To run the code successfully error handling, authentication, a user with id "billy" and a token imported to the first provider with token id "d9f804ac-262a-406b-9a15-6501c2b4e13d" has to be present. 

    public static final int ACTIVE  = 0;
    public static final int ON_HOLD = 1;
    public static final int REVOKED = 2;

    // Locate account web service
    OATHService locator = new OATHService();
    OATH service = locator.getOATH();

    // Get OATH properties for "billy"
    OathProperties oathProps = service.getOATHProperties(subject, "billy");

    // Get the providers available
    List<Provider> providers = service.getProviders(subject);

    // Add a token to the OathProperties list
    OATHToken oathToken = new OATHToken();
    oathToken.setEnabled(true);                                    // enabled
    oathToken.setProvider(providers.get(0));                       // provider
    oathToken.setRevocationStatus(ACTIVE);                         // status
    oathToken.setTokenId("d9f804ac-262a-406b-9a15-6501c2b4e13d");  // tokenId

    // Populate list with a token that "billy" shall have
    oathProps.getOathTokens().add(oathToken);
    // Set OATH password (this is only relevant if using two factor OATH)
    oathProps.setPassword("newPassword");
    // Then enable OATH
    oathProps.setEnabled(true);

    // Finally update the settings on "billy" (the username is stored in the oathProps so it
    // is not necessary to assign explicitly)
    service.updateOATHProperties(subject, oathProps);

Copyright © 1999-2023, Technology Nexus Secured Business Solutions AB. All rights reserved.