Security
In general most OAuth 2.0 security guidelines apply to Ory Polis as well but there are a few minor differences.
Tenancy
OAuth 2.0 is typically a single instance and all users can login using the same instance. However SAML is based on an specific instance that your customers have to configure with their Identity Provider. This means that access to the SAML instance is limited to only those that have been provisioned for it, adding another layer of security to the login flow.
Client secret
The Config API returns a client_id and client_secret that you can save for each customer and use when initiating the OAuth 2.0
flow. However for convenience we also let you use a tenant and product instead since this doesn't require you to store any
additional data. When using this we recommend you use the
CLIENT_SECRET_VERIFIER configuration and not use the default dummy value. The
client_secret cannot really be misused because as you will see in the next section the tokens are short lived but it is a good
idea to set the client_secret to something that is really a secret.
For client-side logins we highly recommend you use the PKCE flow which is supported by Ory Polis. This ensures a secure login
without revealing the client_secret on the client-side.
Tokens
The tokens generated by Ory Polis are short lived (default is 5 minutes) and hence there is no risk of it being misused even if
the client_secret is known. Your SAML provider ensures that there can be no unauthorized.
API authentication and request paths
The management APIs under /api/v1/ require an API key, sent as Authorization: Api-Key <key>, where <key> is one of the
values in API_KEYS. The Admin Portal requires a signed-in session instead. The two are not
interchangeable: an API key does not open the Admin Portal, and an Admin Portal session does not call the management APIs.
Use the paths exactly as the API reference shows them, in lower case. Changing the case of the leading /api or /admin segment
is rejected with 401 Unauthorized, whether or not the request carries an API key or an Admin Portal session. Changing the case
of a later segment is not a supported way to call an API and may be rejected the same way. Path parameters such as a directory ID
are matched exactly and keep their own case.
Whatever the spelling, a request reaches a handler only after passing that route's check.
If a reverse proxy or load balancer sits in front of Ory Polis, make sure it passes request paths through unchanged.
Software bill of materials reports
Ory Polis publishes a software bill of materials (SBOM) for the service, the Docker image and the npm package with every release. See SBOM reports for where to find them and how to retrieve them.
