Update README.md

- Align the README file with the template available in the charm-guide
- Add a section to explain how to authenticate using the OpenStack
  client.

Change-Id: Iac6fadab1c19ffa9f8da60ccd37d7c81328b51db

README.md

@@ -1,44 +1,112 @@
 # Overview
 
-This subordinate charm provides a way to integrate a Open ID Connect based
+This subordinate charm provides a way to integrate an Open ID Connect based
 identity provider with Keystone using
-[mod_auth_openidc](https://github.com/zmartzone/mod_auth_openidc). Apache
-operates as a OpenID Connect Relaying Party towards an OpenID Connect
+[mod_auth_openidc][mod_auth_openidc]. Apache
+operates as an OpenID Connect Relaying Party towards an OpenID Connect
 Provider.
 
 # Usage
 
-Use this charm with the [Keystone charm](https://charmhub.io/keystone):
+## Configuration
+
+To display all configuration option information run `juju config
+keystone-openidc`. If the application is not deployed then see the charm's
+[Configure tab][keystone-openidc-configure] in the
+Charmhub. Finally, the [Juju documentation][juju-docs-config-apps] provides
+general guidance on configuring applications.
+
+## Deployment
+
+These deployment instructions assume the following applications are present:
+[keystone][keystone-charm] and
+[openstack-dashboard][openstack-dashboard-charm]
+
+To deploy keystone-openidc:
 
-    juju deploy keystone
-    juju deploy openstack-dashboard
     juju deploy keystone-openidc
+
+Join keystone-openidc to keystone:
+
     juju add-relation keystone:keystone-fid-service-provider keystone-openidc:keystone-fid-service-provider
+
+Join keystone-openidc to openstack-dashboard to provide SSO access through Horizon:
+
     juju add-relation openstack-dashboard:websso-fid-service-provider keystone-openidc:websso-fid-service-provider
 
 
-In a bundle:
+Now provide an OpenID Connect client credentials and the URL for autodiscovery
+of the backend's configuration:
+
+    juju config keystone-openidc \
+        oidc-client-id="<CLIENT_ID>" \
+        oidc-client-secret="<CLIENT_SECRET>" \
+        oidc-provider-metadata-url="https://example.com/.well-known/openid-configuration"
+
+Here is a bundle representation of the deployment:
 
 ```yaml
 applications:
   keystone-openidc:
     charm: ch:keystone-openid
     num_units: 0
+    options:
+      oidc-client-id: "<CLIENT_ID>"
+      oidc-client-secret: "<CLIENT_SECRET>"
+      oidc-provider-metadata-url: "https://example.com/.well-known/openid-configuration"
 relations:
 - - keystone:keystone-fid-service-provider
   - keystone-openidc:keystone-fid-service-provider
+- - openstack-dashboard:websso-fid-service-provider
+  - keystone-openidc:websso-fid-service-provider
 ```
 
-# Prerequisites
+## OpenStack CLI Authentication
 
+The [OpenStack client][openstackclient-homepage] supports authentication
+against an OpenID Connect identity provider using [Bearer Access Token
+authentication flow][bearer-access-token-flow] only. This requires the
+keystone-openidc charm to have its configuration option `auth-type` set to
+'auth-openidc' (the default).
+
+Here is an example of the environment variables that need to be set for the
+OpenStack client to authenticate successfully:
+
+```bash
+export OS_AUTH_TYPE=v3oidcpassword
+export OS_DISCOVERY_ENDPOINT="https://example.com/.well-known/openid-configuration"
+
+export OS_OPENID_SCOPE="openid email profile"
+export OS_CLIENT_ID="<CLIENT_SECRET>"
+export OS_CLIENT_SECRET="<CLIENT_SECRET>"
+export OS_IDENTITY_PROVIDER=openid
+export OS_PROTOCOL=openid
+
+# At the end include openstack specific config, like OS_USERNAME, OS_PASSWORD, etc.
+# ...
+```
+
+<!-- To test the example above run the following commands in a local copy of
+the keystone-openidc git repo:
+
+  tox -e build
+  tox -e func-target -- jammy-yoga --keep-model
+-->
 
 # Bugs
 
-Please report bugs on [Launchpad][lp-bugs-charm-keystone-openidc].
+Please report bugs on [Launchpad][keystone-openidc-filebug].
 
 For general charm questions refer to the [OpenStack Charm Guide][cg].
 
 <!-- LINKS -->
 
+[bearer-access-token-flow]: https://www.rfc-editor.org/rfc/rfc6750
 [cg]: https://docs.openstack.org/charm-guide
-[lp-bugs-charm-keystone-openidc]: https://bugs.launchpad.net/charm-keystone-openidc/+filebug
+[juju-docs-config-apps]: https://juju.is/docs/olm/configure-an-application
+[keystone-openidc-configure]: https://charmhub.io/keystone-openidc/configure
+[keystone-openidc-filebug]: https://bugs.launchpad.net/charm-keystone-openidc/+filebug
+[keystone-charm]: https://charmhub.io/keystone
+[mod_auth_openidc]: https://github.com/zmartzone/mod_auth_openidc
+[openstackclient-homepage]: https://docs.openstack.org/python-openstackclient/latest/
+[openstack-dashboard-charm]: https://charmhub.io/openstack-dashboard