Consume auth sessions
Learn how to authenticate your users and take actions on their behalf.
Before you start this document, the following is recommended:
- Understand core Intuned concepts
- Understand API and recorder generated auth sessions
- Understand the development of an project with auth session enabled
Creating an auth session
To create an auth session the following must be prepared:
- [Required] Access to user credentials, ether it is stored or the user is present
- [Optional] Proxy to the location you wish to have the user authenticate from
Intuned supports two methods to create an auth session Intuned Client APIs and Intuned Portal.
Intuned Client APIs is generally recommended to be used in production. Especially when you are building a custom user experience to allow your users to capture and manage their auth sessions within your service.
Learn how to create auth sessions using APIs:
Intuned Portal is generally recommended to be used in testing. It can also be used if you’re automating back-office tasks.
Learn how to create auth sessions using Intuned Portal:
Utilizing auth Sessions
Calling an API in an project with auth sessions enabled requires an auth session to be present. Prior to executing any APIs, Intuned will check if the auth session is valid by attempting to call the auth-sessions/check
API that is defined in the project.
After creating an auth session, it must be included in input payload of the direct API calls. If jobs or queues are being configured on an project with auth sessions enabled then the configuration must include auth session as well.
Learn how to utilize auth sessions:
- POINTER to guide 1 on making a direct async call
- POINTER to guide 1 on calling a job
- POINTER to guide 1 on auth session calling a queue
Managing auth session
Proxies
An auth session can be configured with a proxy to ensure all actions are showing up from the same IP address. Proxies are not required to use auth sessions but is commonly used if the target service has forces two factor authentication when detecting different user behavior.
Once an auth session is configured with a proxy all API calls with this auth session will be routed via the proxy so if the proxy fails the API calls will fail as well. If there are failures in the proxy, you can update the proxy configured on an auth session.
Auth session states
An auth session may fall into one of the following states:
- Ready - Upon successful creation an auth session remains in this state until it no longer valid.
- Expired - Auth session reaches this state once the auth session check fails. To fix an expired auth session you can simply update the auth session.
The state diagrams below show the state for auth sessions:
Updating auth sessions
Once an auth session has been created, it should serve as the only auth session instance for that user/service pairing. For example is Sam created an auth session for Service A with the id sam-sA-session
then this auth session should be maintained and updated by you. This means that you must update and maintain the auth session for the duration you need it.