Overview

OA4MP is an OAuth 2 issuer, meaning that it creates tokens. It must set itself as the originator of the token by asserting an iss claim wherever needed. E.g., https://math.bigstate.edu/oauth2. A common situation is that an institution requires that the issuer be scoped to itself (so all of the tokens used by group X have an issuer indicated they were created for group X) and have its own set of signing keys. The issuer claim reflects this, e.g. If the Geometry group at Big State University wanted to set up a token issuer for all of its users, a reasonable iss claim in the tokens would be https://math.bigstate.edu/oauth2/geometry. Specialized issuers are really quite handly since they can ensure that tokens can be ignored or not misued. As such, once savored, people tend to want to have an issuer for each and every project, group, department, you name it.

What we don't want is a proliferation of services, with, say, an install for every issuer since that makes for a vast and unremitting maintenance headache. For one thing, there must be a discovery (aka .well-known) page for the issuer that is different from the main page of the server. Keys have to generated, managed and all of the little tasks multiply rapidly and are not trivial. Fortuantely, OA4MP supports virtual issuers aka VI in the sequel. This makes adding a virtual issuer quite straightforward. You install OA4MP, then create all the virtual issuers you want or need.

What's a virtual issuer?

This is simply a facility that takes some basic information about what the issuer should do and does it. Much of the machinery is auto-generated by OA4MP so setting up a virtual issuer for an organization is quite simple. Indeed, it usually just works.

How do they work?

It is important to understand that if an admin clients use virtual issuers, and then all of the clients it manages us the VI as well. This makes it easy to manage a large system of clients who have specialized signing requirements. (Historical note, these were called virtual organization for a time, but that names was taken over by other projects unrelated to OA4MP, causing confusion. We hence switched to calling these virtual issuers. If you run into the term virtual organization, let us know to fix it and rock on.)

Relation to administrative clients

After you create a VI, you simply set it for the admin client using the add_admin command in the CLI (in the vi component). This does all the necessary bookkeeping. Note that if an admin client is set to use a virtual issuer, every client it administers automagically now uses that issuer. A practical ramification is that if you convert an admin to using a VI, then any existing flows may break. It is therefore best to set up the VI and the admin(s) before actually creating clients. On the other hand, it does give a great way to move all of your clients to using a VI in one fell swoop.

Creating a virtual issuer

You need to use the CLI for this. Important prerequisites are that you know what the issuer's name (simple strings are best, such as cern or jpl. Remember that these will end up in URIs as part of identifiers, so complex escaping will make it unreadable.

Discovery aka well-known pages

As per the RFC 8414 specification, the main discovery page for the OA4MP server hosted at https://math.bigstate.edu would be https://math.bigstate.edu/.well-known/openid-configuration. If you have a virtual issuer name geometry then the discovery page must be located at https://math.bigstate.edu/.well-known/openid-configuration/geometry. Internally, OA4MP will generate these live at https://math.bigstate.edu/oauth2/.well-known/openid-configuration/geometry (assuming you deployed OA4MP to the standard endpoint of oauth2) and simply return requests for the VI's discovery page. This allows you to always just check what is actually there.

An example

In this case OA4MP has been set up at the (mythical) university of Edgestow. The task is to create an issuer for an installed OA4MP server (at https://math.edgestow.edu/oauth2). In the example that follows, lines of input are numbered and the section after has commentary on each line. This seems to be the most readable way to do it. Output from the CLI is not numbers, only user input.

 0. oa4mp>use vi
 1.   vi>create edgestow:geometry
 2. object created, edit (y/n)?y
     Update the values. A return accepts the existing or default value in []'s
     For properties you can type /help or --help and print out the online help for the topic.
 3. enter the identifier[edgestow:geometry]:
 4. enter description[--]:Issuer for Differential Geometry at the University of Edgestow
 5. enter the title[--]:Issuer for Differential Geometry at the University of Edgestow
 6. enter the issuer[--]:https://math.edgestow.edu/oauth2/geometry
 7. enter the access token issuer[https://math.edgestow.edu/oauth2/geometry]:
 8. enter the discovery path. NOTE this should be of the form host/path e.g.cilogon.org/ligo:[--]:math.edgestow.edu/geometry
 9. Did you want to specify a file with the JSON web keys(y/n)[n]:
10. Did you want to create a new set?[n]:y
11. enter type RSA or EC:[RSA]:
12. Enter key size (default is 2048)
      Found keys are:
        1A11D7F309DDF102: alg =RS256, use=sig
        01FF6CEA64431C8F: alg =RS384, use=sig
        C51F2F847B928C4B: alg =RS512, use=sig
13. enter the default key id[1A11D7F309DDF102]:
      here is the complete object:

           at_issuer : https://math.edgestow.edu/oauth2/geometry
              created : 1730744581287
       default_key_id : 1A11D7F309DDF102
    description : Issuer for Diffe... lots more lines!
14. save (y/n)? y
      Updates saved

Create the virtual issuer with the given ID. The ID is a URI and should be readable. If you do nto supply one, the system will create a random one for you.
Prompt to edit the newly created object. You can edit it later, but it will have nothing useful in it and will not work until you finish configuring it.
One last change to alter the identifier if you wish.
The description is a text string for you to describe to yourself what this is and what it does
The title is show in other contexts to identify this VI.
The issuer for this VI. This is asserted as the iss claim in the ID token.
The access token issuer for this VI. When a JWT for the access token is created, this is asserted as the iss claim. By default this the same as the ID token issuer.
The discovery path. There is a longer note below about this. It should be the host name and the issuer's moniker it will use in the discovery path
This allows you to either create the generate the keys (answer n to be prompted for creating them) or specify an existing JWK (JSON WebKey) format file. Answer y to be prompted for the path to the file. This example assumes youa re auto-generating the keys.
Prompt to generate the keys. y generates them and displays the ID
Enter the key type. The two types are RSA and EC (for elliptic curve). Each will prompt you for any specifics to that set of keys. Here we accept the default of RSA.
For RSA keys, the key leangth is required. The larger the key size, the better the security and the longer key generation takes. Note that the key length must be a multiple 256. Each geenrated key has a unique identifier. These are printed and the most common one for whatever the set is, is selected as the default for signing.
If you wish to select a different default key than the one given, select it from the printed list and paste it (or type) it in. It is case sensitive.
The entire record is printed and you are asked if you want to save it. If you answer n then the entire set of edits is lost, requiring that you set up the record manually.

Tips

You can always enter --help (note double hyphen!) at the prompt and get a help for the given topic, e.g. for the identifier prompt you could issue

   enter the identifier[edgestow:geometry]:--help
        -----
        Property: Identifier (**)
        A standard unique identifier for this VI. Note that any admin client in the VI will use this to identify
        the VI. Set it for the admin using the add_admin command.
        -----
        enter the identifier[edgestow:geometry]:

Default values for the property are in the []'s and the default of "--" means no value is set. Just hit return if you want to accept the default value.
This is all live. To check that it works, try the well-known page at https://math.edgestow.edu/.well-known/openid-configuration/geometry" which should be a page that lists all of the appropriate configuration (such as the generated keys).

Example of setting the VI for an admin client

Assuming we have an admin client whose identifier is oa4mp:/admin/edgestow/geometry The proper sequence to set the above VI is

    vi>set_id edgestow:geometry
    vi>add_admin oa4mp:/admin/edgestow/geometry
virtual issuer "edgestow:geometry" set for admin with id "oa4mp:/admin/edgestow/geometry"

Setting up the discovery path using the CLI

This corresponds to the attribute discovery_path in the CLI's record for the VI. This has a slightly different syntax than you might expect. It is of the form

host/vi

E.g. if your server is deployed at math.bigstate.edu and your vi is geometry, then the entry is

math.bigstate.edu/geometry

Why specify the path? Because OA4MP can live in quite exotic configurations and this tells the system how to generate the general page as expected by the clients. If you have a single instance of OA4MP running, just use the host name and be done with it.

For instance, there may be half a dozen OA4MP instances on different servers with completely random names that are behind a load balancer that presents itself as the service at math.bigstate.edu. Requests to this endpoint are forwarded by the load balancer to one of these OA4MP instances. The generated response should have actual name of the service, not that of the local machine servicing the request.

OA4MP

Project Documentation