← Back to branch summary

~ubuntu-branches/ubuntu/vivid/libapache2-mod-auth-openidc/vivid-proposed

« back to all changes in this revision

Viewing changes to README.md

  • Committer: Package Import Robot
  • Author(s): Hans Zandbelt
  • Date: 2014-10-13 12:23:35 UTC
  • mfrom: (1.1.3)
  • Revision ID: package-import@ubuntu.com-20141013122335-31wgnq50ascmubib
Tags: 1.6.0-1
new upstream release; add libssl-dev dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
README.md
9
9
--------
10
10
 
11
11
This module enables an Apache 2.x web server to operate as an [OpenID Connect]
12
 
(http://openid.net/specs/openid-connect-core-1_0.html) *Relying Party*. The module
13
 
supports all defined OpenID Connect flows, including *Basic Client Profile*,
14
 
*Implicit Client Profile* and *Hybrid flows*. 
 
12
(http://openid.net/specs/openid-connect-core-1_0.html) *Relying Party* (RP) to an
 
13
OpenID Connect *Provider* (OP). It will enable users to authenticate at an OpenID
 
14
Connect Provider, receive user identity information from the OP in a so called ID
 
15
Token and pass the identity information (a.k.a. claims) in the ID Token to applications
 
16
hosted and protected by the Apache web server.
15
17
 
16
18
The protected content and/or applications can be served by the Apache server
17
19
itself or it can be served from elsewhere when Apache is configured as a reverse
18
20
proxy in front of the origin server(s).
19
21
 
20
 
By default it sets the `REMOTE_USER` variable to the `id_token` `[sub]` claim,
21
 
concatenated with the OP's Issuer identifier (`[sub]@[iss]`). Other
22
 
`id_token` claims are passed in HTTP headers together with those
23
 
(optionally) obtained from the UserInfo endpoint.
 
22
By default the module sets the `REMOTE_USER` variable to the `id_token` `[sub]` claim,
 
23
concatenated with the OP's Issuer identifier (`[sub]@[iss]`). Other `id_token`
 
24
claims are passed in HTTP headers together with those (optionally) obtained from
 
25
the UserInfo endpoint.
24
26
 
25
27
It allows for authorization rules (based on standard Apache `Require` primitives)
26
28
that can be matched against the set of claims provided in the `id_token`/
27
 
`userinfo`.
 
29
`userinfo` claims.
28
30
 
29
 
It supports connecting to multiple OpenID Connect Providers through reading/writing
30
 
provider metadata files in a specified metadata directory.
 
31
This module supports all defined OpenID Connect flows, including *Basic Client Profile*,
 
32
*Implicit Client Profile* and *Hybrid flows*. It supports connecting to multiple OpenID
 
33
Connect Providers through reading/writing provider metadata files in a specified metadata directory.
31
34
 
32
35
It supports [OpenID Connect Dynamic Client Registration]
33
36
(http://openid.net/specs/openid-connect-registration-1_0.html) and [OpenID Provider
34
37
Discovery] (http://openid.net/specs/openid-connect-discovery-1_0.html) through domain
35
38
or account names.
36
39
 
 
40
It supports [OpenID Connect Session Management draft 21]
 
41
(http://openid.net/specs/openid-connect-session-1_0.html). See the [Wiki]
 
42
(https://github.com/pingidentity/mod_auth_openidc/wiki) for information
 
43
on how to configure it.
 
44
 
37
45
Additionally it can operate as an OAuth 2.0 Resource Server to a [PingFederate]
38
46
(https://www.pingidentity.com/products/pingfederate/) OAuth 2.0 Authorization Server,
39
47
validating Bearer access_tokens against [PingFederate](https://www.pingidentity.com/products/pingfederate/).
61
69
 
62
70
###Sample Config for Google Accounts
63
71
 
64
 
Sample configuration for using Google as your OpenID Connect Provider running on
 
72
Sample configuration*) for using Google as your OpenID Connect Provider running on
65
73
`www.example.com` and `https://www.example.com/example/redirect_uri` registered
66
74
as the *redirect_uri* for the client through the Google API Console. You will also
67
75
have to enable the `Google+ API` under `APIs & auth` in the [Google API console]
68
76
(https://console.developers.google.com).
69
77
 
 
78
    OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration
 
79
    OIDCClientID <your-client-id-administered-through-the-google-api-console>
 
80
    OIDCClientSecret <your-client-secret-administered-through-the-google-api-console>
 
81
 
 
82
    OIDCScope "openid email profile"
 
83
    OIDCRedirectURI https://www.example.com/example/redirect_uri
 
84
    OIDCCryptoPassphrase <password>
 
85
 
 
86
    OIDCCookiePath /example/
 
87
 
 
88
    <Location /example/>
 
89
       AuthType openid-connect
 
90
       Require valid-user
 
91
    </Location>
 
92
 
 
93
*) OIDCProviderMetadataURL is supported from version 1.6.0rc2 onwards. For older versions you'll 
 
94
need to specify individual provider configuration entries manually, as in:
 
95
 
70
96
    OIDCProviderIssuer accounts.google.com
71
 
    OIDCProviderAuthorizationEndpoint https://accounts.google.com/o/oauth2/auth[?hd=<your-domain>]
 
97
    OIDCProviderAuthorizationEndpoint https://accounts.google.com/o/oauth2/auth
72
98
    OIDCProviderTokenEndpoint https://accounts.google.com/o/oauth2/token
73
99
    OIDCProviderTokenEndpointAuth client_secret_post
74
100
    OIDCProviderUserInfoEndpoint https://www.googleapis.com/plus/v1/people/me/openIdConnect
75
101
    OIDCProviderJwksUri https://www.googleapis.com/oauth2/v2/certs
76
102
 
77
 
    OIDCClientID <your-client-id-administered-through-the-google-api-console>
78
 
    OIDCClientSecret <your-client-secret-administered-through-the-google-api-console>
79
 
 
80
 
    OIDCScope "openid email profile"
81
 
    OIDCRedirectURI https://www.example.com/example/redirect_uri
82
 
    OIDCCryptoPassphrase <password>
83
 
    OIDCCookiePath /example/
84
 
 
85
 
    <Location /example/>
86
 
       AuthType openid-connect
87
 
       Require valid-user
88
 
    </Location>
89
 
 
90
103
Note if you want to securely restrict logins to a specific Google Apps domain you would not only
91
 
use the `hd` parameter to the `OIDCProviderAuthorizationEndpoint` for skipping the Google Account
 
104
add the `hd=<your-domain>` setting to the `OIDCAuthRequestParams` primitive for skipping the Google Account
92
105
Chooser screen, but you **must** also use the following authorization setting in the `Location` primitive:
93
106
 
94
107
    Require claim hd:<your-domain>
141
154
    "userinfo_encrypted_response_alg"    overrides OIDCUserInfoEncryptedResponseAlg
142
155
    "userinfo_encrypted_response_enc"    overrides OIDCUserInfoEncryptedResponseEnc
143
156
    "auth_request_params"                overrides OIDCAuthRequestParams
 
157
    "token_endpoint_params"              overrides OIDCProviderTokenEndpointParams
144
158
    "registration_token"                 an access_token that will be used on client registration calls for the associated OP
145
159
 
146
160
Sample client metadata for issuer `https://localhost:9031`, so the **mod_auth_openidc**
175
189
 
176
190
Sample callback:
177
191
 
178
 
    <oidc_callback>?target_link_uri=<target_link_uri>&iss=[<issuer>|<domain>|<e-mail-style-account-name>]
 
192
    <oidc_callback>?target_link_uri=<target_link_uri>&iss=[<issuer>|<domain>|<e-mail-style-account-name>][&login_hint=<name>][&auth_request_params=<urlencoded-query-string>]
179
193
 
180
194
This is also the OpenID Connect specified way of triggering 3rd party initiated SSO 
181
195
to a specific provider when multiple OPs have been configured. In that case the callback
182
196
may also contain a "login_hint" parameter with the login identifier the user might use to log in.
183
197
 
 
198
An additional **mod_auth_openidc** specific parameter named `auth_request_params` may also be passed
 
199
in, see the [Wiki](https://github.com/pingidentity/mod_auth_openidc/wiki#10-how-can-i-add-custom-parameters-to-the-authorization-request)
 
200
for its usage.
184
201
 
185
202
###Sample Config for PingFederate OpenID Connect & OAuth 2.0
186
203
 
187
 
Another example config for using PingFederate as your OpenID Connect OP and/or
 
204
Another example config*) for using PingFederate as your OpenID Connect OP and/or
188
205
OAuth 2.0 Authorization server, based on the OAuth 2.0 PlayGround 3.x default
189
206
configuration and doing claims-based authorization. (running on `localhost` and
190
207
`https://localhost/example/redirect_uri/` registered as *redirect_uri* for the
191
208
client `ac_oic_client`)
192
209
 
193
 
    OIDCProviderIssuer https://macbook:9031
194
 
    OIDCProviderAuthorizationEndpoint https://macbook:9031/as/authorization.oauth2
195
 
    OIDCProviderTokenEndpoint https://macbook:9031/as/token.oauth2
196
 
    OIDCProviderTokenEndpointAuth client_secret_basic
197
 
    OIDCProviderUserInfoEndpoint https://macbook:9031/idp/userinfo.openid
198
 
    OIDCProviderJwksUri https://macbook:9031/pf/JWKS
 
210
    OIDCProviderMetadataURL https://macbook:9031/.well-known/openid-configuration
199
211
 
200
212
    OIDCSSLValidateServer Off
201
213
    OIDCClientID ac_oic_client
225
237
       Require claim Username:joe
226
238
    </Location>
227
239
 
 
240
*) for versions older than 1.6.0rc2 you cannot use `OIDCProviderMetadataURL` and you'll need to
 
241
specify the provider configuration entries manually, as in:
 
242
 
 
243
    OIDCProviderIssuer https://macbook:9031
 
244
    OIDCProviderAuthorizationEndpoint https://macbook:9031/as/authorization.oauth2
 
245
    OIDCProviderTokenEndpoint https://macbook:9031/as/token.oauth2
 
246
    OIDCProviderTokenEndpointAuth client_secret_basic
 
247
    OIDCProviderUserInfoEndpoint https://macbook:9031/idp/userinfo.openid
 
248
    OIDCProviderJwksUri https://macbook:9031/pf/JWKS
 
249
 
228
250
Support
229
251
-------
230
252