This section describes the basic concepts of OSP.
The configuration template for OSP resides in the osp-conf.jar file. The template includes information from the following resources:
ism-configuration.properties file
User Application configuration locations including Identity Vault and the file system
Most of the OSP properties are configured by using the Configuration Update utility (configupdate.sh or configupdate.bat).
OAuth-defined authentication provides two types of tokens: access token and refresh token.
Access token is a bearer token. Any entity that obtains an access token may use the token. To keep away the chances of unauthorized access, the lifetime of an access token is typically very short.
Refresh token is used when possibility of token leakage is low. For example, when the token is held on a server than in a browser. A refresh token can be used to obtain an access token without requiring the user to re-enter the credentials. The lifetime of a refresh token is typically quite long.
The authentication process involves a number of different and related timeout values. The two most important timeout values are:
OAuth access token lifetime (default value is 120 seconds)
OSP session timeout (session time-to-live; default value is 20 minutes)
Each time an access token expires, the application requests a new access token from OSP. Each time a browser request is made to OSP, the session time-to-live token is reset. Therefore, as long as a user is using an application and the application is getting new access tokens, the user is not logged out.
A refresh token allows an application to obtain a new access token without user interaction. Refresh tokens are used by applications that can keep them secure. Therefore, refresh tokens have long lifetimes (default 30 days although effective lifetime is 48 hours due to revocation timeout). The identity applications use refresh tokens in the backend.
OSP automatically revokes a refresh token that was obtained through a browser-based request when an OSP session is logged out.
Applications that obtain refresh token through a backend request use the http[s]://<host>[:port]/osp/a/idm/auth/oauth2/revoke endpoint as described in RFC 7009. A refresh token obtained through OAuth 2.0 Resource Owner Password Grant (backend name/password method) must be manually revoked. If a refresh token is not revoked through session logout or through a backend request, then the token revocation information remains in the oidpInstanceData (osp.sch) attribute on the LDAP user object. When a user does not log out of the identity applications, OSP does not remove the login entry from the oidpInstanceData. If the user continues to log in without logging out, the size of the entry grows large and prevents OSP from updating the attribute and eventually causes login failure for the user. For troubleshooting this issue, see Managing the Size of oidPInstancedata Attribute.
OSP uses the following types of cookies in the authentication process:
OSP Session Cookie: Records user information, such as user identifier and time-to-live. It is stored in temporary memory and not retained after the browser is closed. This type of cookie is removed when a user closes the web browser. Absence or expiry of this cookie means that the user is not authenticated.
OAuth2 Cookie: Records OAuth 2.0 state between redirects. The default settings of Microsoft browsers sometimes prevent the submission of OSP cookies to the OSP server that can be determined by using browser developer tools or the OSP log.
The identity applications require JavaScript to implement interactions with OSP.
The open source project, Spiffy UI, provides an easy way to interact with OSP when using Google Web Toolkit (GWT). For detailed information, see the following resources:
http://www.spiffyui.org
https://github.com/spiffyui?tab=repositories
If using AngularJS, the following project may be helpful: https://github.com/Gromit-Soft
OSP uses the following URLs in authentication:
grant
getattributes
logout
Examples used in the following sections assume a secured connection (HTTPS), where OSP is hosted on a server named authentication host with the default port 8443, and the tenant is named idm.
Invoke this URL in a browser: https://authenticationhost:8443/osp/a/idm/auth/oauth2/grant
This is the OAuth 2.0 Authorization endpoint defined by Section 3.1 of RFC 6749.
An implicit grant request can look similar to this:
https://authenticationhost:8443/osp/a/idm/auth/oauth2/grant?response_type=token&redirect_uri=http://applicationhost:8180/landing/com.netiq.ualanding.index/oauth.html&client_id=ualanding&state=spiffystate0.5457210745662451
The allowable HTTP methods and parameters are as defined in Section 4 of RFC 6749.
Invoke this URL in a browser: https:// authenticationhost:8443/osp/a/idm/auth/oauth2/getattributes
This is the OAuth 2.0 Token endpoint defined by Section 3.2 of RFC 6749. The identity applications issue this token to obtain identity information about the entity for which an access token was created. The identity information is presented in the form of attributes (name-value pairs).
A token validation request from a web page can look similar to this:
https://authenticationhost:8443/osp/a/idm/auth/oauth2/getattributes?attributes=name+expiration&access_token=eHwA[...etc.]&callback=jQuery20305550091890618205_1463435676921&_=1463435676922
The desired attributes are specified by a space-separated list of attribute names using the “attributes” query item. The available attributes and their names are primarily defined by the tenant's authentication configuration in authcfg.xml. There are also several pre-defined attributes related to token management.
Invoke this URL in a browser: https://authenticationhost:8443/osp/a/idm/auth/app/logout
This is an OSP-specific endpoint that identity applications use to inform OSP that a user has requested a logout and that OSP must invalidate the OSP session information from the encrypted browser cookie. Typically this endpoint is invoked when a user selects Logout link on the identity application's web page.