Skip to content

Commit f0966d4

Browse files
authored
reshuffle README.md and move Google Accounts to a Wiki page
1 parent d1d6a65 commit f0966d4

File tree

1 file changed

+44
-81
lines changed

1 file changed

+44
-81
lines changed

README.md

Lines changed: 44 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,50 @@ listed [here](https://github.com/OpenIDC/mod_auth_openidc/wiki/Caching).
3636
For a complete overview of all configuration options, see the file [`auth_openidc.conf`](https://github.com/OpenIDC/mod_auth_openidc/blob/master/auth_openidc.conf).
3737
This file can also serve as an include file for `httpd.conf`.
3838

39-
Interoperability
40-
----------------
39+
How to Use It
40+
-------------
41+
42+
1. install and load `mod_auth_openidc.so` in your Apache server
43+
1. set `OIDCRedirectURI` to a "vanity" URL within a location that is protected by mod_auth_openidc
44+
1. configure a random password in `OIDCCryptoPassphrase` for session/state encryption purposes
45+
1. configure `OIDCProviderMetadataURL` so it points to the Discovery metadata of your OpenID Connect Provider served on the `.well-known/openid-configuration` endpoint
46+
1. register/generate a Client identifier and a secret with the OpenID Connect Provider and configure those in `OIDCClientID` and `OIDCClientSecret` respectively
47+
1. register the `OIDCRedirectURI` configured above as the Redirect or Callback URI for your client at the Provider
48+
1. configure your protected content/locations with `AuthType openid-connect`
49+
50+
A minimal working configuration would look like:
51+
```apache
52+
LoadModule auth_openidc_module modules/mod_auth_openidc.so
53+
54+
# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
55+
OIDCRedirectURI https://<hostname>/secure/redirect_uri
56+
OIDCCryptoPassphrase <password>
57+
58+
OIDCProviderMetadataURL <issuer>/.well-known/openid-configuration
59+
OIDCClientID <client_id>
60+
OIDCClientSecret <client_secret>
61+
62+
<Location /secure>
63+
AuthType openid-connect
64+
Require valid-user
65+
</Location>
66+
```
67+
For claims-based authorization with `Require claim:` directives see the [Wiki page on Authorization](https://github.com/OpenIDC/mod_auth_openidc/wiki/Authorization). For details on configuring multiple providers see the [Wiki](https://github.com/OpenIDC/mod_auth_openidc/wiki/Multiple-Providers).
68+
69+
### Quickstart for specific Providers
70+
71+
- [Keycloak](https://github.com/OpenIDC/mod_auth_openidc/wiki/Keycloak)
72+
- [Microsoft Entra ID (Azure AD)](https://github.com/OpenIDC/mod_auth_openidc/wiki/Microsoft-Entra-ID--(Azure-AD))
73+
- [Google Accounts](https://github.com/OpenIDC/mod_auth_openidc/wiki/Google-Accounts)
74+
- [Sign in with Apple](https://github.com/OpenIDC/mod_auth_openidc/wiki/Sign-in-with-Apple)
75+
- [GLUU Server](https://github.com/OpenIDC/mod_auth_openidc/wiki/Gluu-Server)
76+
- [Curity Identity Server](https://github.com/OpenIDC/mod_auth_openidc/wiki/Curity-Identity-Server)
77+
and [more](https://github.com/OpenIDC/mod_auth_openidc/wiki/Useful-Links)
78+
79+
See the [Wiki](https://github.com/OpenIDC/mod_auth_openidc/wiki) for configuration docs for other OpenID Connect Providers.
80+
81+
Interoperability and Supported Specifications
82+
---------------------------------------------
4183

4284
*mod_auth_openidc* is [OpenID Certified™](https://openid.net/certification/#OPENID-RP-P) and supports the following specifications:
4385
- [OpenID Connect Core 1.0](http://openid.net/specs/openid-connect-core-1_0.html) *(Basic, Implicit, Hybrid and Refresh flows)*
@@ -66,85 +108,6 @@ For questions, issues and suggestions use the Github Discussions forum at:
66108
For commercial - subscription based - support and licensing please contact:
67109
68110

69-
How to Use It
70-
-------------
71-
72-
### OpenID Connect SSO with Google+ Sign-In
73-
74-
Sample configuration for using Google as your OpenID Connect Provider running on
75-
`www.example.com` and `https://www.example.com/example/redirect_uri` registered
76-
as the *redirect_uri* for the client through the Google API Console. You will also
77-
have to enable the `Google+ API` under `APIs & auth` in the [Google API console](https://console.developers.google.com).
78-
79-
```apache
80-
OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration
81-
OIDCClientID <your-client-id-administered-through-the-google-api-console>
82-
OIDCClientSecret <your-client-secret-administered-through-the-google-api-console>
83-
84-
# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
85-
OIDCRedirectURI https://www.example.com/example/redirect_uri
86-
OIDCCryptoPassphrase <password>
87-
88-
<Location /example/>
89-
AuthType openid-connect
90-
Require valid-user
91-
</Location>
92-
```
93-
94-
Note if you want to securely restrict logins to a specific Google Apps domain you would not only
95-
add the `hd=<your-domain>` setting to the `OIDCAuthRequestParams` primitive for skipping the Google Account
96-
Chooser screen, but you must also ask for the `email` scope using `OIDCScope` and use a `Require claim`
97-
authorization setting in the `Location` primitive similar to:
98-
99-
```apache
100-
OIDCScope "openid email"
101-
Require claim hd:<your-domain>
102-
```
103-
104-
The above is an authorization example of an exact match of a provided claim against a string value.
105-
For more authorization options see the [Wiki page on Authorization](https://github.com/OpenIDC/mod_auth_openidc/wiki/Authorization).
106-
107-
### Quickstart with a generic OpenID Connect Provider
108-
109-
1. install and load `mod_auth_openidc.so` in your Apache server
110-
1. configure your protected content/locations with `AuthType openid-connect`
111-
1. set `OIDCRedirectURI` to a "vanity" URL within a location that is protected by mod_auth_openidc
112-
1. register/generate a Client identifier and a secret with the OpenID Connect Provider and configure those in `OIDCClientID` and `OIDCClientSecret` respectively
113-
1. and register the `OIDCRedirectURI` as the Redirect or Callback URI with your client at the Provider
114-
1. configure `OIDCProviderMetadataURL` so it points to the Discovery metadata of your OpenID Connect Provider served on the `.well-known/openid-configuration` endpoint
115-
1. configure a random password in `OIDCCryptoPassphrase` for session/state encryption purposes
116-
117-
```apache
118-
LoadModule auth_openidc_module modules/mod_auth_openidc.so
119-
120-
OIDCProviderMetadataURL <issuer>/.well-known/openid-configuration
121-
OIDCClientID <client_id>
122-
OIDCClientSecret <client_secret>
123-
124-
# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
125-
OIDCRedirectURI https://<hostname>/secure/redirect_uri
126-
OIDCCryptoPassphrase <password>
127-
128-
<Location /secure>
129-
AuthType openid-connect
130-
Require valid-user
131-
</Location>
132-
```
133-
For details on configuring multiple providers see the [Wiki](https://github.com/OpenIDC/mod_auth_openidc/wiki/Multiple-Providers).
134-
135-
### Quickstart for Other Providers
136-
137-
See the [Wiki](https://github.com/OpenIDC/mod_auth_openidc/wiki) for configuration docs for other OpenID Connect Providers:
138-
- [GLUU Server](https://github.com/OpenIDC/mod_auth_openidc/wiki/Gluu-Server)
139-
- [Keycloak](https://github.com/OpenIDC/mod_auth_openidc/wiki/Keycloak)
140-
- [Microsoft Entra ID (Azure AD)](https://github.com/OpenIDC/mod_auth_openidc/wiki/Microsoft-Entra-ID--(Azure-AD))
141-
- [Sign in with Apple](https://github.com/OpenIDC/mod_auth_openidc/wiki/Sign-in-with-Apple)
142-
- [Curity Identity Server](https://github.com/OpenIDC/mod_auth_openidc/wiki/Curity-Identity-Server)
143-
- [LemonLDAP::NG](https://github.com/OpenIDC/mod_auth_openidc/wiki/LemonLDAP::NG)
144-
- [GitLab](https://github.com/OpenIDC/mod_auth_openidc/wiki/GitLab-OAuth2)
145-
- [Globus](https://github.com/OpenIDC/mod_auth_openidc/wiki/Globus)
146-
and [more](https://github.com/OpenIDC/mod_auth_openidc/wiki/Useful-Links)
147-
148111
Disclaimer
149112
----------
150113

0 commit comments

Comments
 (0)