Using a REST web service to authenticate with an application
For API key authentication, you put an authorization code in a Static credential property or define an HTTP user ID and password. The input device or notification passes the authorization code or the HTTP user ID and password to the web service that exchanges data. The web service then authenticates with the application and returns a response.
For session authentication, you put authentication credentials (user ID and password) and other values in a set of authentication request properties. The input device or notification first calls a REST web service to authenticate with the application. After a successful authentication, the web service returns a token to the input device or notification. The input device or notification then transmits the token in the call to the web service that exchanges data.
- If the application allows one session per user, set up your input devices and notifications to call the web services with different user IDs and passwords.
- Session authentication occurs with every web service call and logging out is not required. Make sure that the length of the session for each set of credentials is shorter than the time between calls to the web service. For example, the session for an input device expires after 10 minutes. When you configure the input device, specify a polling interval greater than 10 minutes.
To get an API key or authentication credentials for an application, contact the company that hosts the application. For format and syntax requirements, refer to the documentation of the application.
- Click the Authentication tab on the REST web service input device or notification.
- Follow the instructions for the type of authentication that the application requires:
- For API key authentication, specify the authentication code as the value of the Static credential property.
Leave all the other properties blank. You have completed this procedure.
- For session authentication, leave the Static credential property blank. Go to the next step and specify the other properties.
- For API key authentication, specify the authentication code as the value of the Static credential property.
- Set the Authentication request URL property to the URL that RICOH ProcessDirector uses to authenticate with the application.
- Specify the authentication credentials by entering values required by the application
in one or more of these properties: Authentication request payload, Authentication request header, and Authentication request parameters.
- For the value of the Request payload property, specify the body (if any) of the authorization request that is submitted
to the application.
In these examples, the payload includes three XML elements: <Credentials>, <Name>, and <Password>. The value of the <Password> element is a symbol that uses the Authentication request password property.
This example uses the Authentication request password property for input devices:
<Credentials> <Name>myname</Name> <Password>${WebService.AuthRequestPwd}</Password></Credentials>
This example uses the Authentication request password property for notifications:
<Credentials> <Name>myname</Name> <Password>${WSNotification.WebService.AuthRequestPwd}</Password></Credentials>
The input device or notification resolves the symbol when it sends the authentication request.
- Set the values for the Request header and Request parameters properties, as required.
Each header field or parameter is a keyword/value pair. Each pair must appear on a separate line and must be separated using a colon (:) or equals sign (=).
The keyword and value can be multiple words. RICOH ProcessDirector uses the first colon or equals sign on each line to split the words into the keyword/value pair.
These examples contain two parameters: name and pwd. The value of the pwd keyword is a symbol that uses the Authentication request password property.
This example uses the Authentication request password property for input devices:
name:mynamepwd:${WebService.AuthRequestPwd}
This example uses the Authentication request password property for notifications:
name:mynamepwd:${WSNotification.WebService.AuthRequestPwd}
The symbol is resolved when the authentication request is sent.
- For the value of the Request payload property, specify the body (if any) of the authorization request that is submitted
to the application.
- Set the Request method and Request content type properties to the values required by the web service.
- Set the Authentication response attribute property to the XPath expression that identifies the credential for the session in the response from the web service.
- Set the Authentication request password property to the password for your account with the application.The password is encrypted when it is stored in RICOH ProcessDirector.
- For input devices, the property is WebService.Credential.
- For notifications, the property is WSNotification.WebService.Credential.
When you specify values on the Request tab for a web service input device or notification, you specify the WebService.Credential or WSNotification.WebService.Credential property as a symbol.
RICOH ProcessDirector substitutes the value of the static credential or token for the symbol when it transmits the request to a web service.
- Preparing to retrieve REST web services input.
- Preparing to send status to a REST web service.