https://github.com/tarachandverma/nginx-openidc
Nginx module for openid-connect relying party, SSO and JWT authentication
https://github.com/tarachandverma/nginx-openidc
Last synced: 12 days ago
JSON representation
Nginx module for openid-connect relying party, SSO and JWT authentication
- Host: GitHub
- URL: https://github.com/tarachandverma/nginx-openidc
- Owner: tarachandverma
- License: mit
- Created: 2016-02-03T14:55:26.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2022-01-07T12:45:56.000Z (over 3 years ago)
- Last Synced: 2025-03-18T00:51:27.375Z (28 days ago)
- Language: C
- Homepage:
- Size: 2.45 MB
- Stars: 77
- Watchers: 5
- Forks: 10
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - tarachandverma/nginx-openidc - Nginx module for openid-connect relying party, SSO and JWT authentication (others)
- jimsghstars - tarachandverma/nginx-openidc - Nginx module for openid-connect relying party, SSO and JWT authentication (C)
README
# nginx-openidc
Nginx module for openid connect relying party and JWT authentication
====================================================================
**nginx-openidc is Nginx module allows openid-connect(JWT) validation and access control based on standard claim as headers.
This document details the technical architecture and reasoning behind the
nginx-openidc system.
The request flow - Relying Party ( RP )
---------------------------------------
1. The user makes a request for a protected resource on RP `ngx-oidc-demo.com` for resource http://ngx-oidc-demo.com/protected.
2. In "Access" phase of nginx, **nginx-openidc** performs a check RP session exists containing the logged-in userinfo.
3. **nginx-openidc** decrypts cookie, verifies payload.
4. On success, The **nginx-openidc** sets request headers X-OIDC-* i.e. X-OIDC-SUBJECT, X-OIDC-ISSUER and many more depending on scopes requested from JWT claim.
5. In post "Access" phase, **nginx-openidc** oidc-config.xml rules are executed.
This is most important phase where you can define unlimited authorization rules based on X-OIDC-* header
6. Upon successfully running rules in post authorization phase, nginx forwards them to the
backend **service** application.
7. The **service** application can use the X-OIDC-* headers as-is.
The request flow - API Gateway
------------------------------------
1. ClientApp gets a JWT from authorized OP or generates a JWT using "client-credentials" flow
2. The clientApp makes a request for a protected API on `ngx-oidc-demo.com` for resource with access_token as "Authorization: Bearer " header.
Examples
http://ngx-oidc-demo.com/api/user.email
Authorization: Bearer
3. In "Access" phase of nginx, **nginx-openidc** performs JWT validation.
4. On success, The **nginx-openidc** sets request headers X-OIDC-* i.e. X-OIDC-SUBJECT, X-OIDC-ISSUER and many more depending on scopes requested from JWT claim.
5. In post "Access" phase, **nginx-openidc** oidc-config.xml rules are executed.
6. Upon successfully running rules in post authorization phase, nginx forwards them to the
backend **service** application.
7. The **service** application can use the X-OIDC-* headers as-is.
Here are the some of the features supported.
Features
------------
- Supports all OAuth2.0/OpenID-Connect flows
- Supports HS256 and RS256
- Supports rotated RS256 public key.
- Implements Access phase which validates id_token(JWT) and passes claims as custom headers
- Implements Post Authorization phase custom response based on custom headers.
- Allows multiple relying party based on callback url
- Allows multiple OpenID-Connect Provider
- Supports "nonce" generation and validation
- Supports relying party session
- Removes custom headers from incoming request to ensure these headers are not spoofed.
- Unlimited capabilities from Authorization to rewrites
- Capabilites to add/remove/update request/response headers
- Capability to generate custom error response
- Support fo auto refresh entire oidc-config.xml and retrieve RS256 publicKeys from JWKS url periodically with no server restart
Supported platforms
--------------------------------------
- All the flavors of *nix platforms, freebsd.
# Installation
``````````
git clone https://github.com/tarachandverma/nginx-openidc.git
cd nginx-openidc
wget 'http://nginx.org/download/nginx-1.14.0.tar.gz'
tar -xzvf nginx-1.14.0.tar.gz
cd nginx-1.14.0/
# Here we assume you would install you nginx under /opt/nginx/.
./configure --add-module=../src --with-http_ssl_module
make
make install
``````````
# Test ( using docker )
#build docker image
- docker build -t nginx-oidc .
#run docker image
- docker run -p 80:80 -p 443:443 -i -t nginx-oidc
#add /etc/hosts entry
- NEW-DOCKER-IP ngx-oidc-demo.com
#access docker container via protected path
- http://ngx-oidc-demo.com/protected
# Example :
````````````````````
X-OIDC-VALIDATE-STATUS = success
X-OIDC-ISSUER = https://accounts.google.com
X-OIDC-SUBJECT = 113146716035256978692
X-OIDC-AUDIENCE = 282412598309-545pvmsh9r23f4k1o7267744s59sod6v.apps.googleusercontent.com
X-OIDC-NONCE = a44df6ae-27f2-4c92-85e1-a22eb6381f53
X-OIDC-EMAIL = [email protected]
X-REQUEST-METHOD = GET
X-REQUEST-SCHEME = http
X-RP-SESSION = 7a6db077-ea64-47b4-ae77-2f438f4803ba
Note: headers available on successful JWT validation ( all header is prefixed with HTTP_ when it reaches to backend app )
````````````````````
# Main Configuration
````````````````````
OPENIDC_HomeDir /usr/local/nginx/conf;
OPENIDC_LogFile oidc-refresh.log;
OPENIDC_SharedMemory file=/config.shm size=61000;
OPENIDC_RemotePath uri=https://raw.githubusercontent.com/tarachandverma/nginx-openidc/master/example-conf/;
OPENIDC_PassPhrase secret123;
OPENIDC_HeaderPrefix X-OIDC-;
OPENIDC_RefreshWaitSeconds 20;
OPENIDC_ConfigFile oidc-config.xml;
````````````````````
- **OPENIDC_HomeDir** Home directory to hold openid configuration and logs files.
Specify description string.
- **OPENIDC_LogFile**
Log file is generated upon startup and refresh and records information whats loaded in shared memory.
- **OPENIDC_SharedMemory**
Specifies shared memory file name and size
- **OPENIDC_RemotePath**
Optional: Specifies remote directory to download oidc-config.xml during startup.
- **OPENIDC_PassPhrase**
Specifies passPhrase to encrypt/decrypt relying party session
- **OPENIDC_HeaderPrefix**
Specifies custom headers prefix for the claims, default:X-OIDC-
- **OPENIDC_RefreshWaitSeconds (mendatory if OP signing keys are rotating )**
This will refresh entire oidc-config.xml remote repository defined by OPENIDC_RemotePath along with OP publicKeys
defined by in oidc-config.xml
default:no refresh
- **OPENIDC_ConfigFile**
Specify relying party configuration and custom post Authorization response and rules
How to enable ngx openid-connect : nginx.conf
---------------------------------------------
`````````````````````
http {
...
OPENIDC_HomeDir /usr/local/nginx/conf;
OPENIDC_LogFile oidc-refresh.log;
OPENIDC_SharedMemory file=/config.shm size=61000;
OPENIDC_RemotePath uri=https://raw.githubusercontent.com/tarachandverma/nginx-openidc/master/example-conf/;
OPENIDC_PassPhrase secret123;
OPENIDC_HeaderPrefix X-REMOTE-;
#OPENIDC_RefreshWaitSeconds 20;
OPENIDC_ConfigFile oidc-config.xml;
server {
...
# authorization code flow - exchanging authorization code to id_token(JWT)
location /internal/oauth2/token {
internal;
proxy_pass https://www.googleapis.com/oauth2/v4/token;
}
}
...
}
`````````````````````
openid-connect configuration : oidc-conf.xml
-------------------------------------------
```XML
$$OP metadata url$$
$$OP authorization_end_point$$
$$OP token_end_point same as defined in nginx.conf's proxy_pass for token endpoint$$
$$OP json web keys end poing$$
nginx oidc demo
$$CALLBACK URL WHERE ID_TOKEN OR CODE WILL BE RECIEVED$$
$$OIDC ISSUER FROM ABOVE LIST TO SELECT APPROPRIATE TOKEN EXCHANGE END-POINT FOR ID_TOKEN$$
nginx oidc demo
$$CALLBACK URL WHERE ID_TOKEN OR CODE WILL BE RECIEVED$$
$$OIDC ISSUER FROM ABOVE LIST TO SELECT APPROPRIATE TOKEN EXCHANGE END-POINT FOR ID_TOKEN$$
...
nginx oidc demo
$$CALLBACK URL WHERE ID_TOKEN OR CODE WILL BE RECIEVED$$
$$OIDC ISSUER FROM ABOVE LIST TO SELECT APPROPRIATE TOKEN EXCHANGE END-POINT FOR ID_TOKEN$$
oidc_version
oidc_config_core_status
oidc_rewrite_pageactions
oidc_rewrite_actionmappings
oidc_rewrite_match
oidc_headers
oidc_index
describe what action does in few words
true/false
true/false
true/false
$$regex-to-generate-tokens-to-build-below-url$$
true/false
$$target-path1
$$header-value$$
$$header-value$$
$$unique identifier of oidcProvider as defined in oidcProviders$$
$$unique identifier of RelyingParry as defined in relyingParties$$
$$host-name-regex$$
$$client-ip-address-regex-or-string$$
$$path-regex-or-string$$
$$header-value1$$
$$header-value2$$
. . .
$$header-value1$$
$$header-value2$$
. . .
. . .
oidc_version
oidc_config_core_status
oidc_rewrite_pageactions
oidc_rewrite_actionmappings
oidc_rewrite_match
oidc_headers
oidc_index
one of the action in above actions-list-1
one of the action in above actions-list-2
. . .
last action, its default action if above action don't match
. . .
```
**mapping** source url
- **path** specifies uri patterns match on source uri
- **oidcAction** specifies action taken in authorization where it can use all the x-oidc-* headers avaiable in the request
- **matchLists** specifies the condition
**action** target action on source url
- **description** specifies what action is all about in couple of words
- **isForward** specifies internal forwared/redirect if set to true
- **isLoginRedirect** specifies initial authorize request to OP meaning automatically adds state=CURRENT_URI and nonce=CSRF_AND_ID_TOKEN_REPLAY protection in initial request
- **uri** specifies the target url which can be generated from source url
- **advancedTemplate** specifies advanced usage to generate target url using various kind of format.
Target url : http://hostname:port/myurl/%{format}
Following format-tags are supported.
'r', requestVariables,
's', serverVariables,
'c', requestCookie,
'u', urlDecodeToken,
'U', urlEncodeToken,
'q', requestQuery
Development
------------
- Source hosted at [GitHub](https://github.com/tarachandverma/nginx-openidc)
- Report issues, questions, feature requests on [GitHub Issues](https://github.com/tarachandverma/nginx-openidc/issues)
Diagnostics
---------------------
- Log file path
- Startup log - /oidc-refresh.log
Related open source (OpenID connect Provider)
---------------------------------------------
https://github.com/tarachandverma/easy-oidc-provider
Authors
-------
[Tara chand Verma]
* * *