From a065533256ac760496d65a2d4fc2e20daed8ea32 Mon Sep 17 00:00:00 2001
From: Eric Stroczynski <ericstroczynski@gmail.com>
Date: Fri, 25 Aug 2017 00:40:36 -0700
Subject: [PATCH] Documentation: OIDC conformance test setup
---
Documentation/oidc-certification-setup.md | 126 ++++++++++++++++++++++
1 file changed, 126 insertions(+)
create mode 100644 Documentation/oidc-certification-setup.md
diff --git a/Documentation/oidc-certification-setup.md b/Documentation/oidc-certification-setup.md
new file mode 100644
index 00000000..81bf45e3
--- /dev/null
+++ b/Documentation/oidc-certification-setup.md
@@ -0,0 +1,126 @@
+# OpenID Connect Provider Certification
+
+The OpenID Foundation provides a set of [conformance test profiles][oidc-conf-profiles] that test both Relying Party and OpenID Provider (OP) OpenID Connect implementations. Upon submission of [results][oidc-result-submission] and an affirmative response, the affirmed OP will be listed as a [certified OP][oidc-certified-ops] on the OpenID Connect website and allowed to use the [certification mark][oidc-cert-mark] according to the certification [terms and conditions][oidc-terms-conds], section 3(d).
+
+## Basic OpenID Provider Tests
+
+Dex is an OP that implements the [mandatory set][oidc-core-spec-mandatory] of OpenID Connect features, and can be tested against the Basic OpenID Provider profile ([profile outline][oidc-conf-profiles], section 2.1.1). These tests ensure that all features required by a [basic client][oidc-basic-client-spec] work as expected.
+
+### Setup
+
+There are two ways to set up an OpenID test instance:
+1. Configure a test instance provided by The OpenID Foundation by following [instructions][oidc-test-config] on their website.
+1. Download their test runner from [GitHub][oidc-github] and follow the instructions in the [README][oidc-github-readme].
+ * Requires `docker` and `docker-compose`
+
+Configuration is essentially the same for either type of OpenID test instance. We will proceed with option 1 in this example, and set up an [AWS EC2 instance][aws-ec2-instance] to deploy dex:
+* Create an [AWS EC2 instance][aws-ec2-quick-start] and connect to your instance using [SSH][aws-ec2-ssh].
+* Install [dex][dex-install].
+* Ensure whatever port dex is listening on (usually 5556) is open to ingress traffic in your security group configuration.
+* In this example the public DNS name, automatically assigned to each internet-facing EC2 instance, is **my-test-ec2-server.com**. You can find your instances' in the AWS EC2 management console.
+
+### Configuring an OpenID test instance
+
+1. Navigate to [https://op.certification.openid.net:60000][oidc-test-start].
+1. Click 'New' configuration.
+1. Input your issuer url: `http://my-test-ec2-server.com:5556/dex`.
+1. Select `code` as the response type.
+1. Click 'Create' to further configure your OpenID instance.
+1. On the next page, copy and paste the `redirect_uris` into the `redirectURIs` config field (see below).
+1. At this point we can run dex, as we have all the information necessary to create a config file (`oidc-config.yaml` in this example):
+ ```yaml
+ issuer: http://my-test-ec2-server.com:5556/dex
+ storage:
+ type: sqlite3
+ config:
+ file: examples/dex.db
+ web:
+ http: 0.0.0.0:5556
+ oauth2:
+ skipApprovalScreen: true
+ staticClients:
+ - id: example-app
+ redirectURIs:
+ - 'https://op.certification.openid.net:${OPENID_SERVER_PORT}/authz_cb'
+ name: 'Example App'
+ secret: ZXhhbXBsZS1hcHAtc2VjcmV0
+ connectors:
+ - type: mockCallback
+ id: mock
+ name: Example
+ ```
+ * Substitute `OPENID_SERVER_PORT` for your OpenID test instance port number, assigned after configuring that instance.
+ * Set the `oauth2` field `skipApprovalScreen: true` to automate some clicking.
+1. Run dex:
+ ```bash
+ $ ./bin/dex serve oidc-config.yaml
+ time="2017-08-25T06:34:57Z" level=info msg="config issuer: http://my-test-ec2-server.com:5556/dex"
+ ...
+ ```
+1. Input `client_id` and `client_secret` from your config file.
+ * The `id` and `secret` used here are from the example config file [`staticClients` field](../examples/config-dev.yaml#L50-L55).
+1. Use data returned by the `GET /.well-known/openid-configuration` API call to fill in the rest of the configuration forms:
+ ```bash
+ [home@localhost ~]$ curl http://my-test-ec2-server.com:5556/dex/.well-known/openid-configuration
+ {
+ "issuer": "http://my-test-ec2-server.com:5556/dex",
+ "authorization_endpoint": "http://my-test-ec2-server.com:5556/dex/auth",
+ "token_endpoint": "http://my-test-ec2-server.com:5556/dex/token",
+ "jwks_uri": "http://my-test-ec2-server.com:5556/dex/keys",
+ "response_types_supported": [
+ "code"
+ ],
+ "subject_types_supported": [
+ "public"
+ ],
+ "id_token_signing_alg_values_supported": [
+ "RS256"
+ ],
+ "scopes_supported": [
+ "openid",
+ "email",
+ "groups",
+ "profile",
+ "offline_access"
+ ],
+ "token_endpoint_auth_methods_supported": [
+ "client_secret_basic"
+ ],
+ "claims_supported": [
+ "aud",
+ "email",
+ "email_verified",
+ "exp",
+ "iat",
+ "iss",
+ "locale",
+ "name",
+ "sub"
+ ]
+ }
+ ```
+ * Fill in all configuration information that the `/.well-known/openid-configuration` endpoint returns, althgouh this is not strictly necessary. We should give the test cases as much information about dex's OP implementation as possible.
+1. Press the 'Save and Start' button to start your OpenID test instance.
+1. Follow the provided link.
+1. Run through each test case, following all instructions given by individual cases.
+ * In order to pass certain cases, screenshots of OP responses might be required.
+
+## Result Submission
+
+Once all test cases pass, submit your results by following instructions listed [on the website][oidc-result-submission].
+
+[dex-install]: https://github.com/coreos/dex/blob/master/Documentation/getting-started.md#building-the-dex-binary
+[aws-ec2-instance]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/concepts.htmlSSH
+[aws-ec2-ssh]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html
+[aws-ec2-quick-start]: http://docs.aws.amazon.com/quickstarts/latest/vmlaunch/step-1-launch-instance.html
+[oidc-core-spec-mandatory]: http://openid.net/specs/openid-connect-core-1_0.html#ServerMTI
+[oidc-basic-client-spec]: http://openid.net/specs/openid-connect-basic-1_0.html
+[oidc-conf-profiles]: http://openid.net/wordpress-content/uploads/2016/12/OpenID-Connect-Conformance-Profiles.pdf
+[oidc-test-config]: http://openid.net/certification/testing/
+[oidc-test-start]: https://op.certification.openid.net:60000
+[oidc-result-submission]: http://openid.net/certification/submission/
+[oidc-cert-mark]: http://openid.net/certification/mark/
+[oidc-certified-ops]: http://openid.net/developers/certified/
+[oidc-terms-conds]: http://openid.net/wordpress-content/uploads/2015/03/OpenID-Certification-Terms-and-Conditions.pdf
+[oidc-github]: https://github.com/openid-certification/oidctest
+[oidc-github-readme]: https://github.com/openid-certification/oidctest/blob/master/README.md
--
GitLab