Skip to end of metadata
Go to start of metadata

OpenAM RESTful API

The OpenAM RESTful API can perform a variety of functions, covering

Token Encoding

The examples throughout this guide are given for an instance of OpenAM with c66Encode for cookies turned on. This gives cookies using '.' and '*' as separators instead of '#', '@' and '='. For example throughout this guide the subject token is

AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.*AAJTSQABMDE.*

Without c66Encode turned on this same token would be returned as

AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg=@AAJTSQABMDE=#

Due to URL Encoding standards, the latter token is not valid as a parameter, as it contains reserved characters. As such the tokenid should be percent encoded before submitting the request.

Authentication

It is possible to authentication to OpenAM using the authenticate service. In its most basic form this can be done with a request in the following format.

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/authenticate?username=<uname>&password=<passwd>

This request returns a token in the format

token.id=AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.*AAJTSQABMDE.*

If you want to authenticate against a different realm or service then the attributes which would normally be included as part of the /UI/Login instead need to be added to a 'uri=' parameter, for example

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/authenticate?username=<uname>&password=<passwd>&uri=realm=<realm_name>%26service=<AuthChain>

The value of the URI parameter must be URL encoded.

In the case of a failed login, the rest interface may return either a UserNotFound or an InvalidPassword exception. If the user has been locked out,  a UserInactive exception is returned.

Logout

Logout is simply a matter of passing the tokenid to the logout process. This means the logout is done using

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/logout?subjectid=AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.*AAJTSQABMDE.*

which will then invalidate the tokenid, and end the associated session.

Token Validation

The next basic operation that the OpenAM RESTful interface offers is to validate tokens. This is offered by the isTokenValid method.

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/isTokenValid?tokenid=AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.*AAJTSQABMDE.*

This will either return boolean=true, in the case that it is a valid token, or return an HTTP-401 in the case of a failure.

Authorization

The authorize REST interface allows queries against the OpenAM policy framework, to enquire as to whether a specific user would have the rights to perform an operation on a given resource. For example

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/authorize?uri=<full_url_of_protected_resource>&action=GET&subjectid=AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.*AAJTSQABMDE.*

This will return boolean=true or boolean=false depending on whether the access is allowed or denied, for the user.

Logging

There is a REST interface for the OpenAM log service, that allows entries to be written to the OpenAM log. This process requires two tokens, the appid, which is a tokenid for an administrative user with permissions to write to the log, and the subjectid, which is the tokenid for the user about whom data is being logged.

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/log?appid=AQIC5wM2LY4SfcwvP5GQo06NbUTbU-UO9sH7LwmNktnWguE.AAJTSQACMDE.&subjectid=AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.AAJTSQABMDE.&logname=<log_to_write>&message=<Message_to_Log>

Token Attribute Retrival

The attribute retrival interface, called attributes, allows all the attributes for a given subjectid token to be retrieved. This request is made up of only the subjectid parameter. An example request would be

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/attributes?subjectid=AQIC5wM2LY4RfckcedfzxGrgVYevbKR-SgBkuemF4Cmm5Qg.*AAJTSQABMDE.*

Which would retrieve all of the attributes for a user in name-value pairs as shown below

userdetails.token.id=AQIC5wM2LY4SfczjTKtQsebe931Z82m-sa-dtLpmeb3e5CY.*AAJTSQACMDE.*
userdetails.attribute.name=uid
userdetails.attribute.value=user2
userdetails.attribute.name=userpassword
userdetails.attribute.value={SSHA}ZAd+/PkJKKRHc/u/VYjdwapVOT5hquisAhw7Qw==
userdetails.attribute.name=sn
userdetails.attribute.value=Two
userdetails.attribute.name=cn
userdetails.attribute.value=user2
userdetails.attribute.name=entrydn
userdetails.attribute.value=uid=user2,ou=people,dc=example,dc=com
userdetails.attribute.name=givenname
userdetails.attribute.value=User
userdetails.attribute.name=inetuserstatus
userdetails.attribute.value=Active
userdetails.attribute.name=dn
userdetails.attribute.value=uid=user2,ou=people,dc=example,dc=com
userdetails.attribute.name=objectclass
userdetails.attribute.value=organizationalPerson
userdetails.attribute.value=person
userdetails.attribute.value=sunIdentityServerLibertyPPService
userdetails.attribute.value=inetorgperson
userdetails.attribute.value=sunFederationManagerDataStore
userdetails.attribute.value=inetUser
userdetails.attribute.value=iPlanetPreferences
userdetails.attribute.value=iplanet-am-managed-person
userdetails.attribute.value=iplanet-am-user-service
userdetails.attribute.value=sunFMSAML2NameIdentifier
userdetails.attribute.value=top

If you specify the parameter names of the parameters you want you can also request session properties like this:

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/attributes?subjectid=AQIC5wM2LY4Sfcztr_xNiwoX4fV9cgnejl0QCwMGmcHyGdo.AAJTSQACMDE.&attributenames=AuthType&attributenames=Host

userdetails.token.id=AQIC5wM2LY4Sfcztr_xNiwoX4fV9cgnejl0QCwMGmcHyGdo.*AAJTSQACMDE.*
userdetails.attribute.name=AuthType
userdetails.attribute.value=DataStore
userdetails.attribute.name=Host
userdetails.attribute.value=172.16.90.20

When retrieving attributes, you can add a refresh=true parameter to the query string in order to reset the subjectid's session idle time to 0. Session idle timeout is typically much smaller than the max life of the session (by default 30 minutes vs. 2 hours), so refresh=true can be especially helpful when you are getting started, still writing attribute retrieval queries by hand on the command line.

Identity Management

The OpenAM RESTful interface has a variety of interfaces which allow for the creation, deletion, updating, and search of identity subjects and their related data within the datastore based upon their properies.

Create Identity

The create interface allows for the creation of various identity types for OpenAM. The following attributes are required in constructing a create request

  • identity_name - Unique name for the identity
  • identity_attribute_names - LDAP attributes to be created for the identity
  • identity_attribute_values_<value_from_identity_attribute_names> - Values for LDAP attributes
  • identity_realm - Which realm the user belongs to
  • identity_type - Which type of identity to create
  • admin - tokenid for a user with permissions to perform the operation

For example to create a user, the following could be used as a request

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/create?identity_name=<username>&identity_attribute_names=userpassword&identity_attribute_values_userpassword=<password>&identity_attribute_names=sn&identity_attribute_values_sn=<SN_of_user>&identity_attribute_names=cn&identity_attribute_values_cn=<CN_of_user>&identity_realm=/&identity_type=user&admin=AQIC5wM2LY4SfcwvP5GQo06NbUTbU-UO9sH7LwmNktnWguE.*AAJTSQACMDE.*

Similarly it would be possible to create a Web or J2EE Agent profile using the create REST call and identity_type of AgentOnly and the relevant parameters.

Update Identity

The update interface allows for the attributes of identity subjects to be changed or added, using a similar format to the create REST interface.

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/update?identity_name=<username>&identity_attribute_names=mail&identity_attribute_values_mail=<email_address>&admin=AQIC5wM2LY4SfcwvP5GQo06NbUTbU-UO9sH7LwmNktnWguE.*AAJTSQACMDE.*

Delete Identity

The delete interface requires only the name and type of the identity you wish to delete and an admin token, as shown in the example below.

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/delete?identity_name=<username>&identity_type=user&admin=AQIC5wM2LY4SfcwvP5GQo06NbUTbU-UO9sH7LwmNktnWguE.*AAJTSQACMDE.*

Search Identities

It is possible to also retrieve identities using the search REST interface, based upon their attributes and values. In this case the following attributes should be included in the request

  • filter - Filter to control search results returned
  • attributes_names - LDAP attributes to be searched against
  • attributes_values_<value_from_attribute_names> - Values for LDAP attributes
  • admin - tokenid for a user with permissions to perform search

The following gives an example of searching for all the users in the database

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/search?filter=*&attributes_names=objecttype&attributes_values_objecttype=people&admin=AQIC5wM2LY4SfcwvP5GQo06NbUTbU-UO9sH7LwmNktnWguE.*AAJTSQACMDE.*

Identity Attribute Retrival

Almost the same as the search, however this returns attributes, instead of identity names. (This appears to be the only way to retrieve attributes of another identity in a specified realm.)

  • name - Name of identity
  • attributes_names - LDAP attributes to be searched against
  • attributes_values_<value_from_attribute_names> - Values for LDAP attributes
  • admin - tokenid for a user with permissions to perform search

The following gives an example of retrieving attributes for "jane" in the realm "/subrealm"

http://<OpenAM_Host>:<Port>/<deploy_uri>/identity/read?name=jane&attributes_names=realm&attributes_values_realm=/subrealm&admin=AQIC5wM2LY4SfcwvP5GQo06NbUTbU-UO9sH7LwmNktnWguE.*AAJTSQACMDE.*

  • No labels

5 Comments

  1. I would love to request a session validate url for this REST API.

    1. Rahul

      I'm hoping you spotted this was the "legacy REST API", and is marked as Deprecated in the  OpenAM 11.02 Release Notes

      There is some documentation in the , but with the "Common REST API" you can validate the token - check out the example code from OpenAM Dev Section 3.6.1 Token Validation (although this is the V12.x documentation set) is below:

       

      $ curl \
       --request POST \
       --header "Content-Type: application/json" \
       http://openam.example.com:8080/openam/json/sessions/AQIC5...?_action=validate
      {"valid":true,"uid":"demo","realm":"/realm"}



  2. Hi All,

    I am new to Forgerock and facing one problem in authentication. When hitting the http://localhost:8080/openam/json/authenticate using postman , Its returns me the token id and success URL :

    {
    "tokenId": "AQIC5wM2LY4Sfcylxw9On_6SjJKF8j82g-TfLos2HEaf-Q4.*AAJTSQACMDEAAlNLABMxNTEyODI0Mzg3MDQ5MjI4NTYyAAJTMQAA*",
    "successUrl": "/openam/console"
    }

    But when i consume this rest API through Java Code, I get auth id as  :

    {"authId":"eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiIH0.eyAib3RrIjogImNlYXI5Y2Q3a2ptdWIyczgyajU2NDFiMDEzIiwgInJlYWxtIjogImRjPW9wZW5hbSxkYz1mb3JnZXJvY2ssZGM9b3JnIiwgInNlc3Npb25JZCI6ICJBUUlDNXdNMkxZNFNmY3owazFfRjZQcl94enk4cjJTNVFQN290LUxqU19RWWdRQS4qQUFKVFNRQUNNREVBQWxOTEFCUXROamN6TmpRNE1EYzVNalF4T0RVNU1UVXpNZ0FDVXpFQUFBLi4qIiB9.ZqD3bOuEpjAfKfqi4UcojqZClrMaFrHlV4w8bKBmeCE","template":"","stage":"DataStore1","header":"Sign in to OpenAM","callbacks":[{"type":"NameCallback","output":[{"name":"prompt","value":"User Name:"}],"input":[{"name":"IDToken1","value":""}]},{"type":"PasswordCallback","output":[{"name":"prompt","value":"Password:"}],"input":[{"name":"IDToken2","value":""}]}]}

     

    Why I am not able to authenticate the user through my web application. I need help please...

     

    1. I suggest checking the headers being sent by each method and compare and contrast them. 

  3. Hi,

    Why are you using http instead of https for authN?

    Thanks!