You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Improve minimal auto-configuration for OIDC login with Okta #25549
Spring Boot supports common OAuth2 providers (facebook, github, google and okta), and provide a set of defaults for those providers. It works really well, I can do:
However, by doing so, I lose the access to everything defined in org.springframework.security.config.oauth2.client.CommonOAuth2Provider.OKTA, most crucially the scopes, which are required for OAuth 2.0 login.
This is because OAuth2ClientPropertiesRegistrationAdapter#getClientRegistration first gets the configuration from the issuer-uri, and only if that's not available, it tries to get the "Common provider". Using issuer-uri overrides everything in the "Common Provider".
I'm inclined to propose a PR for this,but I'm curious what are your thoughts on this first?
The idea would be to get the "Common provider" first, and the enhance it through issuer-uri auto-discovery. I'm a bit worried about the impact this would have on the other three "common providers", as your registration would have more information, coming from the discovery endpoint.
I totally agree with 1, subdomain is too specific and wouldn't fit in the auto-config.
re:2, what you describe is currently what is happening. If we use an issuer-uri, we don't use the common provider values at all. The values selected are the following:
Values from the discovery endpoint, including some defaults from spring-security if some of the values are either null or have multiple options, see for example ClientRegistrations#getClientAuthenticationMethod which selects which token_endpoint_auth_methods_supported should be used.
Whatever values the user specifies (these take precedence)
This is works very well except for the scopes.
Scopes are very provider-specific. OIDC adds some standard scopes, but you can add whatever you want. So spring-security refrains from setting default scopes, which makes sense.
The OIDC discovery endpoint does have an optional scopes_supported claim, see OIDC Discovery spec. However these scopes are provider-specific, not client-specific. Not every client will want to use every available scope[1], e.g. I may not want to use offline_access.
So it feels there no "easy" way to set default scopes from an issuer-uri-defined provider.
I guess I could re-frame the problem this way:
google, github and facebook registrations are great, I only need client-id and client-secret
okta, on the other hand, is complicated. The subdomain will always make the provider entry required, which is OK. But either I set the important endpoint URIs by hand, and I get the "correct" OIDC-login-related scopes for free from the CommonOAuth2Providers.OKTA; or I only set the one issuer-uri , and I have to find out which are the correct scopes because otherwise my scopes are null and users cannot do an OIDC login.
I have a feeling there are two possibilities:
We can make it work with both issuer-uri + OAuth2CommonProvider
Or we basically drop Okta support in the docs, because the user has to discover either which provider settings or which scopes are required to make it work
I don't understand why scopes will be null if Okta returns a set of scopes from the OIDC Discovery Endpoint. You mentioned that scopes_supported by the discovery endpoint are provider specific and not client specific. But isn't that also true for the scopes in CommonOAuth2Providers.OKTA? Not every client would want all those scopes provided by the default provider.
@jzheaux pointed me to this issue about not including scopes from scopes_supported in the client registration. That explains why the scopes are empty even if the discovery endpoint returns them.
Joe's comment indicates that leaving scopes empty so that a client explicitly configures them is desired. In that case, using default scopes for every client doesn't seem to align with that.
@jgrandja Can you comment on whether you think we should use scopes from CommonOAuth2Provider instead of having the client explicitly configure them?
I agree with the issue mentioned. scopes_supported represent all available scopes for that given provider, regardless of the client. There might be a lot of those, that may not be relevant to most applications.
However CommonOAuth2Provider.OKTA...scopes is an opinion by the Spring team(s) on what sensible "default scopes" should be - a very valuable opinion! The user can always override them if they have specific needs. So every "default" client, auto-configured by Boot, gets those scopes. In the case of OKTA, Spring Security tells us "a sensible default is openid + profile + email".
Today it's difficult for a user to get these defaults:
they must specify provider.okta.authorization-uri
and provider.okta.token-uri
and provider.okta.jwk-set-uri
and they must omit provider.okta.issuer-uri
In my opinion, we should go with one of the following:
To get the default scopes for Okta, users only need to specify provider.okta.issuer-uri
Okta is not mentioned as one of the "providers with defaults" in Spring Boot anymore.
So I wonder if the following flow would be reasonable:
Get the CommonOAuth2Provider based on registrationId or registration.provider
Enhance from issuer-uri if possible
Override any provider value when a value is specified by the client
Override any registration value when a value is specified by the client
The drawback here is when the users had no scopes configured, we would be adding them. Having no scopes configured means "trust the authorization server to give me the correct default scopes".
By default, I think Okta does not use default scopes, you have to configure them manually in your Okta account.
Sorry for the delay @Kehrlann. I think since the scopes_supported is an exception to what gets copied over from the metadata, we could probably limit values from CommonOAuth2Provider when an issuer_uri is specified to scopes only. So probably something like:
Create the builder from issuer-uri
Add scopes if it is a common provider
Override any provider value when a value is specified by the client
Override any registration value when a value is specified by the client
@Kehrlann@mbhave Just to give some context around why CommonOAuth2Provider was created in the first place.
When we released 5.0 with the new OAuth 2.0 support, CommonOAuth2Provider was provided as a convenience for the oauth2Login() feature.
CommonOAuth2Provider.OKTA.scope defaults to openid, profile, email, which makes sense for an OAuth 2.0 Client that performs OpenID Authentication. However, not every Okta ClientRegistration needs to perform OpenID Authentication.
For example, let's say we have an application that has multiple ClientRegistration's configured with only Okta as the provider. It is most likely only one of those ClientRegistration will perform OpenID Connect and the other ones will simply perform other grant types/flows. Therefore, it doesn't make sense to default all the ClientRegistration to CommonOAuth2Provider.OKTA.scope and most likely the scope setting is overridden with the scopes the client is configured to request.
CommonOAuth2Provider.OKTA.scope is really meant as a convenience for a simple OAuth application performing oauth2Login(). But for production applications, it is likely that the ClientRegistration properties are fined tuned and this most definitely would include the scope property IMO.
As far as the provider metadata scopes_supported goes, this should not be used to default ClientRegistration.scope. This is simply what scopes the provider supports (for any client to use). However, there are custom scopes that are registered with the provider that a client may use that are NOT returned in the scopes_supported. This metadata value is more of a common (or standard) list of scopes supported.
I feel the current logic within Boot and Security is correct and I don't feel any changes are needed here. It is more secure to be in control of properties set in ClientRegistration than relying on defaults. CommonOAuth2Provider was simply provided as a convenience for the simple basic configuration cases but for production grade applications, I would advise on explicitly configuring specific properties and scope would qualify as one of those.
Hi, I'd like to work on this if it's still open for contributions. I couldn't find a PR following the earlier offer, so I assume nobody is working on it.
My understanding of the plan agreed in this comment, with the steps in this one, is as follows. When issuer-uri is set, the builder would still come from ClientRegistrations.fromIssuerLocation. Only the scopes of a matching CommonOAuth2Provider would be added, and then the existing provider and registration properties would be applied as they are today.
An explicit scope on the registration would still win, and a non-common id such as okta-oidc would keep empty scopes. This does change behavior for any common provider id used with issuer-uri and no scope (in practice okta, or google if configured that way), so I'd add a note to the common providers section of the OAuth2 client reference docs. I realize 4.2 is already in RC, so this would probably be for a later minor.
Would a PR along those lines be welcome? I'd send it with tests for both the common and non-common cases.
Activity
mbhave commentedon Mar 9, 2021
It sounds like there are two issues here.
For 1, I think having a subdomain is pretty Okta specific and it doesn't seem like something we can add that would be generally useful.
For 2, my thought was that if the is a OpenID discovery endpoint available, values from that should be used in its entirety.
@Kehrlann Is there a reason why the OP Metadata does not contain the scopes that you need?
/cc @jzheaux Do you think it would make sense to use values from the common providers even when a discovery url is provided?
Kehrlann commentedon Mar 9, 2021
I totally agree with 1, subdomain is too specific and wouldn't fit in the auto-config.
re:2, what you describe is currently what is happening. If we use an
issuer-uri, we don't use the common provider values at all. The values selected are the following:token_endpoint_auth_methods_supportedshould be used.This is works very well except for the scopes.
spring-securityrefrains from setting default scopes, which makes sense.scopes_supportedclaim, see OIDC Discovery spec. However these scopes are provider-specific, not client-specific. Not every client will want to use every available scope[1], e.g. I may not want to useoffline_access.So it feels there no "easy" way to set default scopes from an
issuer-uri-defined provider.I guess I could re-frame the problem this way:
google,githubandfacebookregistrations are great, I only needclient-idandclient-secretokta, on the other hand, is complicated. The subdomain will always make theproviderentry required, which is OK. But either I set the important endpoint URIs by hand, and I get the "correct" OIDC-login-relatedscopes for free from theCommonOAuth2Providers.OKTA; or I only set the oneissuer-uri, and I have to find out which are the correct scopes because otherwise myscopesare null and users cannot do an OIDC login.I have a feeling there are two possibilities:
issuer-uri+ OAuth2CommonProvider[1]: Okta seems to have a different set of
scopes_supportedin the OIDC Discovery Endpoint and in the OAuth 2.0 Server Metadata but I think my point is still valid.mbhave commentedon Mar 11, 2021
I don't understand why
scopeswill benullif Okta returns a set of scopes from the OIDC Discovery Endpoint. You mentioned thatscopes_supportedby the discovery endpoint are provider specific and not client specific. But isn't that also true for the scopes inCommonOAuth2Providers.OKTA? Not every client would want all those scopes provided by the default provider.mbhave commentedon Mar 11, 2021
@jzheaux pointed me to this issue about not including scopes from
scopes_supportedin the client registration. That explains why the scopes are empty even if the discovery endpoint returns them.Joe's comment indicates that leaving scopes empty so that a client explicitly configures them is desired. In that case, using default scopes for every client doesn't seem to align with that.
@jgrandja Can you comment on whether you think we should use scopes from
CommonOAuth2Providerinstead of having the client explicitly configure them?Kehrlann commentedon Mar 12, 2021
I agree with the issue mentioned.
scopes_supportedrepresent all available scopes for that given provider, regardless of the client. There might be a lot of those, that may not be relevant to most applications.However
CommonOAuth2Provider.OKTA...scopesis an opinion by the Spring team(s) on what sensible "default scopes" should be - a very valuable opinion! The user can always override them if they have specific needs. So every "default" client, auto-configured by Boot, gets those scopes. In the case of OKTA, Spring Security tells us "a sensible default isopenid+profile+email".Today it's difficult for a user to get these defaults:
provider.okta.authorization-uriprovider.okta.token-uriprovider.okta.jwk-set-uriprovider.okta.issuer-uriIn my opinion, we should go with one of the following:
provider.okta.issuer-uriSo I wonder if the following flow would be reasonable:
registrationIdorregistration.providerissuer-uriif possibleprovidervalue when a value is specified by the clientregistrationvalue when a value is specified by the clientThe drawback here is when the users had no scopes configured, we would be adding them. Having no scopes configured means "trust the authorization server to give me the correct default scopes".
By default, I think Okta does not use default scopes, you have to configure them manually in your Okta account.
mbhave commentedon Jun 23, 2021
Sorry for the delay @Kehrlann. I think since the
scopes_supportedis an exception to what gets copied over from the metadata, we could probably limit values fromCommonOAuth2Providerwhen anissuer_uriis specified to scopes only. So probably something like:@jgrandja What are your thoughts on this?
Kehrlann commentedon Jun 29, 2021
Behavior seems good. If Joe greenlights this, and if it works for you, I'd be interested in submitting a PR for this.
jgrandja commentedon Jun 29, 2021
@Kehrlann @mbhave Just to give some context around why
CommonOAuth2Providerwas created in the first place.When we released
5.0with the new OAuth 2.0 support,CommonOAuth2Providerwas provided as a convenience for theoauth2Login()feature.CommonOAuth2Provider.OKTA.scopedefaults toopenid, profile, email, which makes sense for an OAuth 2.0 Client that performs OpenID Authentication. However, not every OktaClientRegistrationneeds to perform OpenID Authentication.For example, let's say we have an application that has multiple
ClientRegistration's configured with only Okta as the provider. It is most likely only one of thoseClientRegistrationwill perform OpenID Connect and the other ones will simply perform other grant types/flows. Therefore, it doesn't make sense to default all theClientRegistrationtoCommonOAuth2Provider.OKTA.scopeand most likely thescopesetting is overridden with the scopes the client is configured to request.CommonOAuth2Provider.OKTA.scopeis really meant as a convenience for a simple OAuth application performingoauth2Login(). But for production applications, it is likely that theClientRegistrationproperties are fined tuned and this most definitely would include thescopeproperty IMO.As far as the provider metadata
scopes_supportedgoes, this should not be used to defaultClientRegistration.scope. This is simply whatscopesthe provider supports (for any client to use). However, there are custom scopes that are registered with the provider that a client may use that are NOT returned in thescopes_supported. This metadata value is more of a common (or standard) list of scopes supported.I feel the current logic within Boot and Security is correct and I don't feel any changes are needed here. It is more secure to be in control of properties set in
ClientRegistrationthan relying on defaults.CommonOAuth2Providerwas simply provided as a convenience for the simple basic configuration cases but for production grade applications, I would advise on explicitly configuring specific properties andscopewould qualify as one of those.mbhave commentedon Oct 14, 2021
Based on comments in spring-projects/spring-security#10308, we will make this change.
havefunatcode commentedon Oct 26, 2026
Hi, I'd like to work on this if it's still open for contributions. I couldn't find a PR following the earlier offer, so I assume nobody is working on it.
My understanding of the plan agreed in this comment, with the steps in this one, is as follows. When
issuer-uriis set, the builder would still come fromClientRegistrations.fromIssuerLocation. Only the scopes of a matchingCommonOAuth2Providerwould be added, and then the existing provider and registration properties would be applied as they are today.An explicit
scopeon the registration would still win, and a non-common id such asokta-oidcwould keep empty scopes. This does change behavior for any common provider id used withissuer-uriand noscope(in practiceokta, orgoogleif configured that way), so I'd add a note to the common providers section of the OAuth2 client reference docs. I realize 4.2 is already in RC, so this would probably be for a later minor.Would a PR along those lines be welcome? I'd send it with tests for both the common and non-common cases.