Wandering Thoughts archives

The three email addresses of OpenID Connect (OIDC) in practice

One of the popular forms of web Single Sign On (SSO) systems is OpenID Connect (OIDC). OIDC has multiple components and is normally used with email addresses, or at least things that look like them, in the form of '<user>@<domain>'. Since there are multiple components, it's possible for components to not agree on these 'email addresses'. If you set up a proper OIDC Identity Provider using your proper email addresses, you probably won't have to worry about this, because everything will be handled by your proper software and likely fit together nicely. If you're quickly assembling a discount OIDC environment, you may wind up stumbling over this.

The first OIDC email address is the address that people will put into the 'your identity' box in whatever website wants to use OIDC authentication against your OIDC IdP. In normal OIDC usage, the domain part of this address will be used to do a WebFinger query, which will be expected to return information for OIDC Identity Provider discovery. Many OIDC applications probably also expect to be able to send email to these email addresses.

This means that if the email address you're using for OIDC is 'fred@test.example.org', there must be a 'test.example.org' HTTPS web server that answers WebFinger requests. If you want to use different OIDC IdPs with different web applications for some reason, you're going to need a different (sub)domain and a different virtual web server for each of them. Conversely, if you want to use 'fred@example.org' in an OIDC test, you need the 'example.org' web server to answer WebFinger requests for your test users.

(This need is one factor that may push you to using 'test.example.org' or things like it in your discount OIDC setup.)

The second OIDC email address is in the JSON that WebFinger is expected to return:

{
  "subject" : "acct:fred@test.example.org",
  [...]
}

Some or many OIDC applications will expect the 'subject' field of this JSON to match the email address that the person entered, so they can be sure they're getting accurate OIDC IdP information for this account. If you accidentally make your discount WebFinger implementation return some other email address, you lose. This means you can't just return a single static WebFinger result for all (valid) users, since the OIDC 'email address' must be correct and it will be different for each person.

The third OIDC email address is in the information that your OIDC IdP will probably return (cf). How your OIDC IdP gets this information itself can vary, but if you're using LDAP, your IdP will probably try to get people's email addresses from that. If you've set up your IdP with its own LDAP server, you can give people whatever email domain you want them to have. However, if you're reusing your organization's normal LDAP server, it will probably tell you that people have their regular organizational email address, which is perhaps not 'fred@test.example.org'. Your OIDC IdP may or may not provide you a way to remap people's email addresses or manually set and override them.

(OIDC applications pretty much have to verify that the email address they got back from your OIDC IdP matches what you put in, because this is their protection against you claiming to be one person but authenticating to your OIDC IdP as another one.)

I'm writing this down because when I set up my discount OIDC environment I stubbed my toes on each of these additional two places. I first got the email addresses wrong in WebFinger results, and then in the OIDC IdP results (which were initially just taking the email address from our regular LDAP servers).