Smarter by Design.Simpler for Business
TR7Enterprise Application Delivery & Security Platform
What is an issuer; what is the OIDC discovery document (.well-known/openid-configuration) for?
Short answer
An issuer is the identity of the IdP that issues tokens; it is an HTTPS address (e.g. https://login.example.com/realms/company) and is written in the iss claim of every ID token it issues. The application verifies with this value that the token was issued by the expected issuer. The OIDC discovery document, on the other hand, is the JSON document that is accessed by appending /.well-known/openid-configuration to the end of the issuer address and that lists the provider's authorization, token, user info and JWKS endpoints and the scopes and methods it supports; it removes the need to enter the endpoints manually one by one (OpenID Connect Discovery 1.0). In TR7 AGS, the Fetch Endpoints from Issuer button in the OAuth2 or OpenID Connect form with Custom Provider selected asks for the Issuer URL and the Route Table in the window that opens; TR7 fetches the document itself over the selected route table and fills in the endpoint fields. Its counterpart in SAML 2.0 is the IdP Entity ID (issuer) field; when it is entered, SAML responses coming from another issuer are rejected.
Where It Is Used in TR7
| Where | Field / label | What for |
|---|---|---|
| AGS → Authentication → Authentication Providers (OAuth2, OpenID Connect; Custom Provider) | Fetch Endpoints from Issuer → Issuer URL, Route Table (default: the Namespace value of the profile) | Fetching the discovery document; the Issuer URL is entered only for this operation and is not saved to the profile |
| Same form | Authorization URL, Token URL, User Info URL, Logout URL, Token Revocation URL, JWKS URI | The endpoints filled in from the discovery document |
| Same form | OAuth Scopes, Enable PKCE, Client Authentication | The fields set according to the scopes, PKCE and client authentication methods announced by the provider |
| AGS → Authentication → Authentication Providers (SAML 2.0) | IdP Entity ID (issuer) | The issuer expected in SAML responses |
Which Fields Does Discovery Fill In?
| Discovery document field | TR7 field |
|---|---|
authorization_endpoint, token_endpoint | Authorization URL, Token URL (if these two fields are not in the document, the operation fails) |
userinfo_endpoint, end_session_endpoint, revocation_endpoint | User Info URL, Logout URL, Token Revocation URL (if they are in the document) |
jwks_uri | JWKS URI; only in the OpenID Connect type |
scopes_supported | OAuth scopes: those of openid, profile, email that are announced |
S256 in code_challenge_methods_supported | Enable PKCE is turned on, the method is SHA256 |
token_endpoint_auth_methods_supported | Client authentication: of client_secret_post, client_secret_basic, none, in that order, the first one supported |
When the document is fetched successfully, the "Endpoint fields were filled from the issuer's discovery document" message appears; the error message starts with "Discovery failed:".
Common Misconceptions
- "The issuer is the address of the provider's website." The issuer is the address of the provider's identity service (it mostly starts with
accounts.,login.orid.); it must be exactly the same as theissvalue in the token, and even a trailing/makes a difference. - "Once discovery is done, TR7 follows endpoint changes on its own." TR7 reads the document only at the moment Fetch Endpoints from Issuer is used; if the provider changes its endpoints, the operation is done again or the fields are updated manually.
- "Discovery is needed for built-in providers too." For built-in providers, the endpoints come from TR7's catalog; the button appears only for Custom Provider.
How it is done in the documentation
