ASF OAuth Documentation


Introduction to ASF OAuth:

The ASF OAuth system provides committers at the Apache Software Foundation with a focal point for services wishing to make use of authentication without security implications around storing sensitive user data. It is used by many Apache services as a means of validating that the user requesting access is a committer within a project in the Apache Software Foundation and has lawful access to the systems in question.

The ASF Oauth system is only available to ASF committers, and no sensitive data (such as your password) is shared between the OAuth system and the service requesting the authentication. The OAuth offers Apache services the following data when you sign in:

  1. Your user-ID.
  2. Your full name.
  3. Your affiliation (committer or foundation member).
  4. Which Project Management Committees (PMCs) you are a member of, including podlings.

To log in via the system, you must use your LDAP credentials. These are what you would typically use when committing code to Apache's git or subversion servers, or accessing private repositories. If you have forgotten your password, you may request a reset via id.apache.org

The OAuth system currently in place was implemented in July of 2019, superseding the original OAUth system which relied on Basic Authentication over HTTPS. The new system uses a login form in order to comply with the wishes and suggestions from our committers.

If you have any questions that are not covered in this documentation, please get in touch with the Apache Infrastructure Team at: users@infra.apache.org.

API Documentation:

The following steps outline how to make use of the ASF OAuth system for your own service:

  1. Your service MUST originate from a *.apache.org hostname and the callback URL MUST use HTTPS.
  2. Create a state object that will hold your service's own temporary request information. The ID of this object MUST be either alphanumerical or hexadecimal and between 10 and 64 characters in length. Dashes are also allowed. You may re-use the same ID, but it is recommended that you do not. We recommend using UUID4 for this ID.
  3. Save your state object locally, and redirect the client to https://oauth.apache.org/auth?state=$stateID&redirect_uri=$callback where:
    • $stateID is the ID of the state object you previously created
    • $callback is a TLS-enabled URL which the OAuth system will redirect to upon successful authentication.
  4. The OAuth system will, upon successful auth, redirect to the callback URL and pass on a code parameter in the URL's query string. If there are any query string parameters in your callback URL, the code will be appended to the existing URL.
  5. From the backend of your service, submit a request to: https://oauth.apache.org/token?code=$code to retrieve the information about the user that just authenticated, in JSON format (see below). This information can only be retrieved once, after which the token is invalidated, and MUST be completed no later than ten minutes after the callback URL was visited.
  6. Verify the request by comparing your own state ID against the state value in the JSON.
An example user JSON result from our token endpoint could be:
    {
        "state": "698da7bb-a273-4b6b-a305-e6d757ed979a",
        "uid": "janedoe",
        "fullname": "Jane Maria Doe",
        "email": "janedoe@apache.org",
        "isMember": false,
        "isChair": true,
        "pmcs": ["httpd", "openoffice", "zeppelin"]
    }
        
An example of the OAuth flow in Python 3 can be found here.