Web Service API

The myOneLogin API provides a SOAP web service for utilizing the myOneLogin service. In order to use the myOneLogin API, you must add the IP address of any servers connecting to the service to your organization's Trusted Destinations list (Site Administration->Site Configuration->Trusted Destinations).

Most of the API calls require you to first authenticate with the myOneLogin API by signing in with your username and password and a security token. The security token for your organization can be found on the Site Administration -> Preferences page. The Preferences page also allows you to generate a new security token. Once authenticated, a new API session is created and you will receive a sessionID. This session will expire just like browser sessions expire when interacting with the myOneLogin site.

WSDL Definition:

https://[organization].myonelogin.com/SAAS/API/1.0/SOA/MOL?wsdl

where:

   [organization] is your myOneLogin organization name.



API Methods

signIn method:

Signs you into the myOneLogin API and starts a new session. Returns a sessionId to be used with subsequent calls to identify your authenticated session.

SigninResult signIn(securityToken, username, password)

where:

   securityToken    is your organization's security token on preferences page
   userName         is the name of the user to authenticate as
   password         is the password of the user to authenticate as

signOut method:

Ends your authenticated myOneLogin API session.

MOLResult signOut(sessionId)

where:

   sessionId    is your sessionId returned by the signIn call

getAppsForOrg method:

Must be signed in to the API as an administrator. Returns a list of all the applications currently subscribed to for your organization.

ApplicationListResult getAppsForOrg(sessionId)

where:

   sessionId    is your sessionId returned by the signIn call

getAppsForUser method:

Must be signed in to the API as an administrator. Returns a list of all the applications active for that user.

ApplicationListResult getAppsForUser(sessionId, userId)

where:

   sessionId    is your sessionId returned by the signIn call
   userId       is the numeric userId (not username) of the user

getApps method:

Returns a list of all the applications the user associated with the session is currently subscribed to.

ApplicationListResult getApps(sessionId)

where:

   sessionId    is your sessionId returned by the signIn call

subscribeUserToApp method:

Must be signed in to the API as an administrator. Subscribes the specified user to the application.

MOLResult subscribeUserToApp(sessionId, userId, appName)

where:

   sessionId    is your sessionId returned by the signIn call
   userId       is the numeric userId (not username) of the user
   appName      is the name of the application to subscribe

subscribeToApp method:

Must be signed in to the API as an administrator or self-subscribe must be turned on for your organization. Subscribes the user associated with the session to the application.

MOLResult subscribeToApp(sessionId, appName)

where:

   sessionId    is your sessionId returned by the signIn call
   appName      is the name of the application to subscribe

searchUsers method:

Must be signed in to the API as an administrator.  Searches for users matching the supplied criteria and returns a limited set of profile information of the matching users (will not include Welcome image and message or security questions).  The match is done as a starts-with, case-insensitive comparison using AND between the criteria.  Any criteria that are set to null are ignored.

UserListResult searchUsers(sessionId, userName, firstName, lastName, email, phone)

where:

   sessionId  is your sessionId returned by the signIn call
   userName   is the partial user name to search for
   firstName  is the partial first name to search for
   lastName   is the partial last name to search for
   email      is the partial email address to search for
   phone      is the partial phone number to search for

getProfile method:

Returns the user profile of the user associated with the session.

UserListResult getProfile(sessionId)

where:

   sessionId   is your sessionId returned by the signIn call

getUserProfile method:

Must be signed in to the API as an administrator. Returns a limited set of profile information of the specified user (will not include Welcome image and message or security questions).

UserListResult getUserProfile(sessionId, userId)

where:

   sessionId    is your sessionId returned by the signIn call
   userId       is the numeric userId (not username) of the user

setProfile method:

Updates your profile information. Only changes values that are non-null, i.e. if email is non-null and all the others are null, the call will only update your email address.

MOLResult setProfile(sessionId, first, last, phone, email)

where:

   sessionId   is your sessionId returned by the signIn call
   first       new first name (or null for no change)
   last        new last name (or null for no change)
   phone       new phone number (or null for no change)
   email       new email address (or null for no change)

setUserProfile method:

Must be signed in to the API as an administrator. Will update the first or last name of the specified userId (all other profile information is not editable by the admin).

MOLResult setUserProfile(sessionId, userId, first, last)

where:

   sessionId   is your sessionId returned by the signIn call
   userId      is the numeric userId (not username) of the user
   first       new first name (or null for no change)
   last        new last name (or null for no change)

getCustomUserData method:

Must be signed in to the API as an administrator.  Returns the custom data blob of the specified user in the MOLResult.message field.

MOLResult getCustomUserData(sessionId, userId)

where:

   sessionId   is your sessionId returned by the signIn call
   userId      is the numeric userId (not username) of the user

setCustomUserData method:

Must be signed in to the API as an administrator.  Updates the custom data blob of the specified user.

MOLResult setCustomUserData(sessionId, userId, customData)

where:

   sessionId   is your sessionId returned by the signIn call
   userId      is the numeric userId (not username) of the user
   customData  is the data to store for the user

getApplicationFields method:

Gets the list of fields and values for the user associated with the session for a specific application. The user must be subscribed to the application.

ApplicationFieldListResult getApplicationFields(sessionId, appId, excludeMaskedValues)

where:

   sessionId        is your sessionId returned by the signIn call
   appId            is the numeric application ID (not name) of the application
   excludeMaskedValues  if true, will not include the values of any password fields

setApplicationFields method:

Sets the values of a list of fields for the user associated with the session for a specific application. The user must be subscribed to the application.

MOLResult setApplicationFields(sessionId, appId, fields)

where:

   sessionId   is your sessionId returned by the signIn call
   appId       is the numeric application ID (not name) of the application
   fields      is the list of ApplicationFields to update

addUser method:

Must be signed in to the API as an administrator.  Return success if the user does not exist and was successfully added.

MOLResult addUser(sessionId,userName,firstName,lastName,email,phone,isAdmin);

where:

   sessionId   is your sessionId returned by the signIn call
   userName    is the username (ie. login name) to add
   firstName   is their first name
   lastName    is their last name
   email       is their email address. An activation code will be sent to this address.
   phone       is their phone number (optional, can be set to null)
   isAdmin     if set to true, will create the user as an admin user, otherwise they will
               be created as a normal user.

deleteUser method:

Must be signed in to the API as an administrator.  Return success if the username exists and was successfully deleted.

MOLResult deleteUser(sessionId, userName)

where:

   sessionId   is your sessionId returned by the signIn call
   userName    is the username to delete

verifyUserExists method:

Must be signed in to the API as an administrator. Return success if the username exists in the organization.

MOLResult verifyUserExists(sessionId, username)

where:

   sessionId    is your sessionId returned by the signIn call
   username     is the username to search for

getAssertion method:

Generates an assertion (SAML) for the user associated with the session.  If the user is subscribed to the application and the application is a Relying Party, it will generate and return the assertion in the MOLResult.message field.

MOLResult getAssertion(sessionId, appId)

where:

   sessionId    is your sessionId returned by the signIn call
   appID        is the id number of the application to generate the assertion for

validateAssertion method:

Validates an assertion (SAML) using the organization’s configured identity providers. If the assertion is successfully validated against one of the organization’s configured identity providers, the username contained in the assertion will be returned in the MOLResult.message field.

MOLResult validateAssertion(sessionId, samlResponse, recipientName)

where:

   sessionId       is your sessionId returned by the signIn call
   samlResponse    is the SAML assertion as a base-64 encoded string
   recipientName   must match the recipient name contained in the SAML assertion

validateAssertionById method:

Validates an assertion (SAML) against a specific identity provider. If the assertion is successfully validated against just that identity provider, the username contained in the assertion will be returned in the MOLResult.message field.

MOLResult validateAssertionById(sessionId, samlResponse, recipientName, idpId)

where:

   sessionId       is your sessionId returned by the signIn call
   samlResponse    is the SAML assertion as a base-64 encoded string
   recipientName   must match the recipient name contained in the SAML assertion
   idpId           the id of the indentity provider to validate against

validateAssertionByName method:

Validates an assertion (SAML) against a specific identity provider. If the assertion is successfully validated against just that identity provider, the username contained in the assertion will be returned in the MOLResult.message field.

MOLResult validateAssertionByName(sessionId,samlResponse,recipientName,idpName)

where:

   sessionId       is your sessionId returned by the signIn call
   samlResponse    is the SAML assertion as a base-64 encoded string
   recipientName   must match the recipient name contained in the SAML assertion
   idpName         the name of the identity provider to validate against

getIdentityProviders method:

Must be signed in to the API as an administrator.  Gets the list of identity providers configured for the organization.

IdentityProviderListResult getIdentityProviders(sessionId)

where:

   sessionId       is your sessionId returned by the signIn call

addIdentityProvider method

Must be signed in to the API as an administrator.  Adds a new identity provider to the organization’s federation configuration.  If successful, returns the unique id of the new identity provider in the MOLResult.message field.

MOLResult addIdentityProvider(sessionId, idpName, profile, orgName, cert,
                                    metaDataUrl, metaData)

where:

   sessionId       is your sessionId returned by the signIn call
   idpName         the name you want to assign this IdP
   profile         is the authentication profile type, which must be one of:
                   "myOneLogin"  - the IdP is another myOneLogin org
                   (must specify orgName)
                   "SAML11_POST" - the IdP uses SAML 1.1 browser post profile
                   (must specify cert)
                   "SAML20_POST" - the IdP uses SAML 2.0 browser post profile
                   (must specify at least one of cert, metaDataUrl or metadata)
   orgName         is the name of the myOneLogin organization
                   (required for myOneLogin)
   cert            is the PEM-format signing certificate
                   (required for SAML11_POST)
   metaDataUrl     is the URL to the IdP's SAML 2.0 metadata
   metadata        is an XML string containing the IdP's SAML 2.0 metadata

modifyIdentityProvider method:

Must be signed in to the API as an administrator.  Modifies an existing identity provider.  Note the profile cannot be changed, instead delete and add a new identity provider.

MOLResult modifyIdentityProvider(sessionId, idpId, idpName, orgName, cert,
                                    metaDataUrl, metaData)

where:

   sessionId       is your sessionId returned by the signIn call
   idpId           the unique Id for this IdP
   idpName         is the name you want to assign to this IdP
   orgName         is the name of the myOneLogin organization
                   (required for myOneLogin)
   cert            is the PEM-format signing certificate
                   (required for SAML11_POST)
   metaDataUrl     is the URL to the IdP's SAML 2.0 metadata
   metadata        is an XML string containing the IdP's SAML 2.0 metadata

deleteIdentityProvider method:

Must be signed in to the API as an administrator.  Deletes an existing identity provider.  Return success if the Identity Provider id exists and was successfully deleted.

MOLResult deleteIdentityProvider(sessionId, idpId)

where:

   sessionId       is your sessionId returned by the signIn call
   idpId           the unique Id for this IdP

getServiceProviders method:

Must be signed in to the API as an administrator.  Gets the list of service providers (or relying parties, applications that accept SAML to authenticate instead of logging in via a form) configured for the organization.

ServiceProviderListResult getServiceProviders(sessionId)

where:

   sessionId       is your sessionId returned by the signIn call

addServiceProvider method:

Must be signed in to the API as an administrator.  Adds a new service provider to the organization’s federation configuration.  If successful, returns the unique id of the new service provider in the MOLResult.message field.

MOLResult addServiceProvider(sessionId, name, description, profile, postUrl,
                                    targetUrl, recipient, audience, lifetime)

where:

   sessionId     is your sessionId returned by the signIn call
   name          is the unique name you want to assign this SP
   description   is the description of this SP
   profile       is the authentication profile type, which must be one of:
                 "SAML11_POST" -the SP uses SAML 1.1 browser post profile
                 "SAML20_POST" -the SP uses SAML 2.0 browser post profile URL to
   postUrl       is the URL to post the SAML to
   targetUrl     Target URL to go to after the post
   recipient     Recipient name to put in the SAML
   audience      Audience name to put in the SAML
   lifetime      how long the SAML is valid for - in seconds (default in 200)

modifyServiceProvider method:

Must be signed in to the API as an administrator.  Modifies an existing service provider.  Note the profile cannot be changed, instead delete and add a new service provider.

MOLResult modifyServiceProvider(sessionId, spId, name, description, postUrl,
                                    targetUrl, recipient, audience, lifetime)

where:

   sessionId      is your sessionId returned by the signIn call
   spId           is the unique id of the SP to modify
   name           is the unique name you want to assign this SP
   description    is the description of this SP
   postUrl        is the URL to post the SAML to
   targetUrl      Target URL to go to after the post
   recipient      Recipient name to put in the SAML
   audience       Audience name to put in the SAML
   lifetime       how long the SAML is valid for - in seconds (default in 200)

deleteServiceProvider method:

Must be signed in to the API as an administrator.  Deletes an existing service provider.  Return success if the Service Provider id exists and was successfully deleted.

MOLResult deleteServiceProvider(sessionId, spId)

where:

   sessionId      is your sessionId returned by the signIn call
   spId           is the unique id of the SP to modify

getFederationMap method:

Must be signed in to the API as an administrator.  Gets the list of mappings between identity providers and service providers, that indicate which identity providers can launch which service providers.

FederationMapListResult getFederationMap(sessionId)

where:

   sessionId      is your sessionId returned by the signIn call

addFederationMap method:

Must be signed in to the API as an administrator.  Adds a new mapping between an identity provider and a service provider If successful, returns the unique id of the new mapping in the MOLResult.message field.

MOLResult addFederationMap(sessionId, idpId, spId)

where:

   sessionId      is your sessionId returned by the signIn call
   ipdId          is the id of the identity provider you want to
                  map (allow) access from
   spId           is the id of the service provider you want to
                  map (allow) access to

deleteFederationMap method:

Must be signed in to the API as an administrator.  Deletes an existing federation mapping.  Return success if the map id exists and was successfully deleted.

MOLResult deleteFederationMap(sessionId, mapId)

where:

   sessionId      is your sessionId returned by the signIn call
   mapId          is the unique Id for this map

autoEnrollUser method:

If auto-enroll is turned on for your organization, will enroll or create a new user. This method does not need a session to be established with signIn first.

MOLResult autoEnrollUser(userName, password, email)

where:

   userName  is the name of the user to enroll
   password  is the password of the user to enroll
   email     is the email address of the user to enroll

validateUser method:

If your organization uses external password validation, this method will validate a given username and password with the external password authority. This method can be used to check that the connection between myOneLogin and the external password authority is functioning. It does not need a session to be established with signIn first.

MOLResult validateUser(String userName, String password) throws

where:

   userName    is the name of the user to validate
   password    is the password of the user to validate

throws:

   MyOneLoginException if either arguments are null.

returns a MOLResult with:

isSuccess = true
if the username and password were successfully validated by the external password authority.
isSuccess = false
if the username and password were not successfully validated by the external password authority (eg, bad username or password).
isSuccess = false, errCode !=0 and a message
if there was a problem validating the username and password with the external password authority (eg, unable to connect).


Return Classes

SignInResult class:

SigninResult {
    Integer errCode; // 0 for success, or an error code indicating the reason for failure
    String errMessage; // if the sign in failed, a text message indicating the reason for failure
    String sessionId; // if successful, a sessionId to be used in subsequent calls
}

MOLResult class:

MOLResult {
    Boolean isSuccess; // did the method call succeed?
    String errCode; // if the method failed, an error code indicating the reason for failure
    String message; // if the method failed, a text message indicating the reason for failure
}

ApplicationListResult class:

ApplicationListResult {
    Integer errCode; // 0 for success, or an error code indicating the reason for failure
    String errMessage; // if the method failed, a text message indicating the reason for failure
    List applications;
}

ApplicationDetails class:

ApplicationDetails {     Integer id; // unique numeric ID for this application
    String name;
    String description;
    String iconUrl; // url to get the icon for the app from the MOL site
}

UserListResult class:

UserListResult {
    Integer errCode; // 0 for success, or an error code indicating the reason for failure
    String errMessage; // if the method failed, a text message indicating the reason for failure
    List users;
}

UserDetails class:

UserDetails {
    Integer userId; // unique numeric ID for this user
    String username;
    String firstName;
    String lastName;
    String email;
    String phone;
    String welcomeMessage;
    byte[] welcomeImage;
    List kba; // list of security questions
}

ApplicationFieldListResult class:

ApplicationFieldListResult {
    Integer errCode; // 0 for success, or an error code indicating the reason for failure
    String errMessage; // if the method failed, a text message indicating the reason for failure
    List fields;
}

ApplicationField class:

ApplicationField {
    String name;
    String label;
    String value;
    Integer fieldType; // type of field, defined below
    String defaultValue;
}
fieldType =
    FieldType_TEXT; // Field is a text box
    FieldType_PASSWORD; // Field is a password text box (masked entry)
    FieldType_CHECK // Field is a check box
    FieldType_RADIO // Field is a radio box
    FieldType_DROP // Field is a drop-down menu

IdentityProviderListResults class:

IdentityProviderListResult {
    Integer errCode;                    // 0 for success, or an error code indicating the
                           // reason for failure
    String errMessage;     // if the method failed, a text message indicating
                           // the reason for failure
    List<IdentityProviderDetails> identityProviders;

}

IdentityProviderDetails class:

IdentityProviderDetails {
      Integer id;          // unique id for this identity provider
      String name;
      String profile;      // profile type, must be one of:
                           //  “myOneLogin” – the IdP is another myOneLogin org
                           //                 (must specify orgName)
                           //  “SAML11_POST” – the IdP uses SAML 1.1 browser
                           //                  post profile (must specify cert)
                           //  “SAML20_POST” – the IdP uses SAML 2.0 browser
                           //                  post profile (must specify at
                           //                  least one of cert, metatDataUrl
                           //                  or metaData
      String orgName;      // org name (required for myOneLogin profile)
      String cert          // PEM-format signing certificate (required for
                           // SAML11_POST and optional for SAML20_POST)
      String metaDataUrl;                  // URL to the IdP’s SAML2.0 metadata (optional for
                           // SAML20_POST)
      String metadata;     // XML string containing the IdP’s SAML 2.0 metadata
                           // (optional for SAML20_POST)
}

ServiceProviderListResults class:

ServiceProviderListResult {
    Integer errCode;                    // 0 for success, or an error code indicating the
                           // reason for failure
    String errMessage;     // if the method failed, a text message indicating
                           // the reason for failure
    List<ServiceProviderDetails> serviceProviders;
}

ServiceProviderDetails class:

ServiceProviderDetails {
      Integer id;          // unique id for this identity provider
      String name;
      String description
      String profile;      // profile type, must be one of:
                           //  “SAML11_POST” – the SP uses SAML 1.1 browser
                           //                  post profile
                           //  “SAML20_POST” – the SP uses SAML 2.0 browser
                           //                  post profile
      String postUrl;                  // URL to post the SAML to
      String targetUrl;                  // Target URL to go to after the post
      String recipient;    // Recipient name to put in the SAML
      String audience;                    // Audience name to put in the SAML
      Integer lifetime;    // how long is the SAML valid for in seconds
                           // (default is 200)
}

FederationMapListResults class:

FederationMapListResult {
    Integer errCode;                    // 0 for success, or an error code indicating the
                           // reason for failure
    String errMessage;     // if the method failed, a text message indicating
                           // the reason for failure
    List<FederationMapDetails> mapping;
}

FederationMapDetails class:

FederationMapDetails {
      Integer id;          // unique id for this map
      Integer idIdentityProvider;    // id of the IdP this map is for
      Integer idServiceProvider;     // id of the SP this IdP is allowed to
                                     // federate to
}


Result Codes

0 SUCCESS
1 Unregistered Organization
2 Unregistered Caller
2 Internal Error
3 Authentication Error
3 Authentication Failure
4 External Authentication Error
6 Auto-enroll Error
7 Invalid Arguments
8 Invalid Security Token
9 Unexpected Error
10 Invalid SessionId
11 User Not Admin
12 Action Not Allowed
13 Invalid application (eg. application name/id does not exist)
14 License error (eg. not enough user licneses to add a user)


validateSaml Web Service

https://developer.myonelogin.com/SAAS/API/1.0/SOA/validateSaml?wsdl

validate

ValidateResult validate(String samlResponse, String recipientName) throws MyOneLoginException

where:

   samlResponse    SAML assertion (base-64 encoded string)
   recipientName   matched against recipient name inside the SAML assertion

ValidateResult class:

The validate() method returns a complex type, ValidateResult:

ValidateResult {
   Boolean isValid; // is the saml response valid?
   String username; // if valid, the username from the saml response
   String message; // if invalid, the reason
}