Page Comparison

Table of Contents
maxLevel 2

With the implementation of

Jira Legacy
server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key PLFM-4585

synapse can now act as an OAuth 2.0 Provider. In order for application clients (See roles in https://tools.ietf.org/html/rfc6749#section-1.1) to use Synapse as a resource server our implementation of the authorization server requires the client application to be registered before issuing authorization codes and access tokens.

Once a client is registered it can perform scoped operations on behalf of the user, at the time of writing we support the openid scope for the Open ID Connect /userInfo service. In the future we will extend the scope (and claims) that would allow access to data that with the user consent.

One of the issues in the OAuth architecture is that while authentication and authorization is decoupled from a client application in a secure manner, establishing trust on the client application is not defined by the specification.

Since that the data that synapse users can access might potentially be sensitive according to the scopes and claims, we need a way to establish trust with a client application by having a process in place to verify that the application will not misuse and/or abuse the system. There is not a standard (automated or manual) procedure for verifying a client in the industry and different companies take different approaches (or choose not to have a verification process).

Google and Facebook have both an automated and manual verification and review process, according to the type of client, scope and claims the client has access to. (See https://developers.google.com/apps-script/guides/client-verification and https://support.google.com/cloud/answer/9110914?hl=en) and https://support.google.com/cloud/answer/9110914?hl=en).

Verification Procedure

As of November 2019 the OAuth Clients needs to be verified in order to be usable. A dedicated OAuth Verification Job in the ops build system has been created to perform verification of a specific client. The following procedure can be used in order to verify a client:

1. Once a request is received and the client needs to be verified, create a new ticket in JIRA with the client id

2. Launch the OAuth Verification Job filling out the required parameters (Note: you will need a Jenkins account):

   1. SESSION_TOKEN: A valid session token for an admin user

   2. CLIENT_ID: the id of the client to verify

   3. ETAG: The etag of the client to verify (this is to ensure that the client didn’t change after the client details were read)

   4. VERIFY_STATUS: Leave enabled (deselecting would un-verify a client)

3. Resolve the related JIRA issue

Initial Implementation

As from the design review meeting held on the 11th of November 2019 the synapse team decided that due to the number of expected use cases a complete verification process is not needed and the initial implementation will be based on white listing on a case by case the oauth clients:

1. Client will not be usable after creation until verified. If a client is being (e.g. to get an authorization code or access token) used while not verified an error message should include a the email to contact in order to verify the client.

2. In the Web Client a form to submit a Jira issue to the ACT team to request the client verification will be shown (as part of

   Jira Legacy
   server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key SWC-4957

   )

3. A user should be blocked in the web client from using a non verified client (

   Jira Legacy
   server System JIRA serverId ba6fb084-9827-3160-8067-8ac7470f78b2 key SWC-5043

   )

4. An administrative API (Only ACT and admins can invoke this endpoint) will be added to verify a client:

   Code Block
   PUT /admin/oauth2/client/{id}/verified?status=<boolean>

The initial proposed design below is still valid and can be taken into account in the future when/if the verification will be extended.

Proposed Approach for Synapse

...

In case of rejection a reason must be included explaining why. A user should be able to update the client and perform another submission after being rejected.

Domain validation

In addition to the manual approval or rejection, we should establish ownership of the domain referred to by the redirect uri (s) in the client as an additional trust layer. Note that while the specification does not enforce the scheme for redirect uris for web application types (See application_type in https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), it allows custom schemes for "native" applications. Since we do not support native applications and the specification does not explicitly forbid it, we can enforce the redirect uri scheme to be https. In this way we can assume that we should always be able to verify the domain ownership.

...

If the sector_identifier_uri is provided during the client registration the list of redirect uris might potentially contain multiple domains. In order for a client to be validated all of the URIs needs to pass the domain validation.

Verification Status

A verification submission is associated with a status, one of: SUBMITTED, REJECTED, APPROVED. A verification approval is tied to the domain validation, the verification will include the information about the domain validation status. The verification cannot be approved if the domain is not validated.

...

We should allow to bypass the verification submission (e.g. for internal use or other mean of verification), in this case a submission from the user is not necessary and the client can be verified with a dedicated API call.

Proposed API

DT = Designated team for the verification review.

API Models

...

OAuthClientVerificationStatus

...

User Interaction

There are three main actors involved in the verification

...

For C, the user should be informed if the client is not verified and the consent should be discouraged.

References

...

https://tools.ietf.org/html/rfc6749

https://tools.ietf.org/html/rfc8252

...