Logins, Sessions, and Authentication in Studio
Login Types
In Studio, it is possible to login in any of the following three ways:
Each is described further in the following sub-sections.
User Credentials
If the system is configured for direct login, then a user can login with their username and password which results in a user session tied to the user whose credentials were used to login. The permissions assigned to that user (defined in Teneo Manager) are then used for all permission checks made using the returned access token.
- Login with username and password using the login endpoint or equivalent client method
- The access token for the session is returned from the call to login
- Pass this access token in all calls to the API (this is handled automatically when using the client)
- Call the logout endpoint or equivalent client method to end the session.
External Identity Provider
If the system is configured for delegated login, then a user can trigger the delegated login process which will allow the user to validate their identity against the external identity provider. This results in a user session tied to the user provided by the external identity provider. The permissions assigned to that user (defined in Teneo Manager) are then used for all permission checks using the returned access token.
- Start the login process by calling the delegated login endpoint or equivalent client method
- Polling the delegated login notification endpoint or equivalent client method retrieves an access token when the validation completes successfully
- Pass this access token in all calls to the API (this is handled automatically when using the client)
- Call the logout endpoint or equivalent client method to end the session.
API Token
In Teneo Manager, it is possible to create an API token associated with a user. This API token can be used in place of an access token when calling the Studio API. The permissions assigned to the associated user (defined in Teneo Manager) are used for all permission checks made using the created API token. With API tokens it is not possible (nor required) to login or logout.
Session Types
User Session
A user session is created whenever a successful login is performed (either with user credentials or via an external provider). If the associated user already has an active user session, then the existing active session will be forcefully ended and the access token for the existing active session will be invalidated. Only 1 user session can be in progress for any given user.
API Session
An API session is created when an API call is made using an API Token and there is not already an active API session. If there is an active API session, then this session is used for the API call. Using an API token associated with a particular user will not invalidate an active user session for the same user.
Multiple API Sessions
Multiple API tokens can be created in Teneo Manager associated with the same user. When these tokens are used to access the API, they will have different sessions. This means that multiple automated processes can be executed without concerns over the session state of one affecting the other - as long as different API tokens are used.
Session Persistence
User sessions expire when logout is called or after a timeout period. API sessions persist for a time after last use of the token and will then expire.
It is advisable to ensure that any session persisted settings are re-applied whenever a script is run as the session may or may not have expired. For example, current customer should be set at the start of the script if the system is using multiple Teneo customers.
Authenticating API Calls
Teneo supports authenticating calls to the API via either:
- access token from credential login
- access token from delegated login
- API token created in Teneo Manager.
Whichever type of token and method of retrieval, the usage is the same and follows the OAuth 2.0 Standard for Bearer Tokens. The token must be passed as an Authorization
HTTP header with the value Bearer {access_token}
. Where {access_token}
is the actual access token or API token value as a string.
Example (Javascript)
For example, to get the latest revision of all solutions on an account:
javascript
1fetch(`${server}/teneo-studio/rest/solution-logs?length=1`, {
2 method: 'get',
3 headers: {
4 "Authorization": `Bearer ${authentication}`,
5 "Content-type": "application/x-www-form-urlencoded"
6 }`
7})
8
Variable | Value |
---|---|
server | The address of the Studio installation |
authentication | The access token from login OR API token |