Skip to content

OpenIDC/ngx_sts_module

Repository files navigation

Build Status

ngx_sts_module

A security token exchange module for the NGINX web server which allows for exchanging arbitrary security tokens by calling into a remote Security Token Service (STS). For an overview and rationale see the Apache version of this module at: https://github.com/OpenIDC/mod_sts/blob/master/README.md.

Quickstart

WS-Trust STS with HTTP Basic authentication and setting the target token in a cookie.

       location /sts/wstrust {
        	STSExchange wstrust https://pingfed:9031/pf/sts.wst
				auth=basic&username=wstrust&password=2Federate&applies_to=urn:pingfed&value_type=urn:pingidentity.com:oauth2:grant_type:validate_bearer&token_type=urn:bogus:token&ssl_verify=false;

            STSVariables $source_token $wst_target_token;
            
            proxy_set_header Cookie STS_COOKIE=$wst_target_token;
            proxy_pass http://echo:8080$is_args$args;            
        }

OAuth 2.0 Resource Owner Password Credentials based Token Exchange with client_secret_basic authentication.

        location /sts/ropc {
			STSExchange ropc https://pingfed:9031/as/token.oauth2
				auth=client_secret_basic&client_id=sts0&client_secret=2Federate&username=dummy&ssl_verify=false;
            
            STSVariables $source_token $ropc_target_token;
            
            proxy_set_header Cookie STS_COOKIE=$ropc_target_token;
            proxy_pass http://echo:8080$is_args$args;            
        }

OAuth 2.0 Client Credentials based token retrieval with client_secret_basic authentication.

        location /sts/cc {        
			STSExchange cc https://keycloak:8443/realms/master/protocol/openid-connect/token
				auth=client_secret_basic&client_id=cc_client&client_secret=mysecret&ssl_verify=false;
          
            set $dummy_variable "notempty";
            STSVariables $dummy_variable $cc_target_token;
            
            proxy_set_header Authorization "bearer $cc_target_token";
            proxy_pass http://echo:8080$is_args$args;            
        }

OAuth 2.0 Token Exchange with client_secret_basic authentication.

        location /sts/otx {
			STSExchange otx https://keycloak:8443/auth/realms/master/protocol/openid-connect/token
				auth=client_secret_basic&client_id=otxclient&client_secret=2Federate&ssl_verify=false;

            STSVariables $source_token $otx_target_token;
            
            proxy_set_header Cookie STS_COOKIE=$otx_target_token;
            proxy_pass http://echo:8080$is_args$args;            
        }        

Configuration

Source Token Retrieval

Cookie:

	map $http_cookie $sts_source_token {
		default "";
		"~*MyCookieName=(?<token>[^;]+)" "$token";
	}

Header:

	map $http_authorization $sts_source_token {
		default "";
		"~*^Bearer\s+(?<token>[\S]+)$" $token;
	}

Query:

	if ($args_token != "not found") {
		$sts_source_token = $args_token
	}

Post:

	# use form-input-nginx-module
	set_form_input $sts_source_token access_token;

Source Token Removal

Remove the source token from the incoming request so it is not proxied to the backend.

Cookie:

	set $new_cookie $http_cookie;
	if ($http_cookie ~ "(.*)(?:^|;)\s*source_token=[^;]+(.*)") {
		set $new_cookie $1$2;
	}
	proxy_set_header Cookie $new_cookie;

Header:

	proxy_set_header Authorization "";

Query:

	if ($args ~ (.*)source_token=[^&]*(.*)) {
		set $args $1$2;
	}
	# cleanup any repeated & introduced 
	if ($args ~ (.*)&&+(.*)) {
		set $args $1&$2;
	}
	# cleanup leading &
	if ($args ~ ^&(.*)) {
		set $args $1;
	}
	# cleanup ending &
	if ($args ~ (.*)&$) {
		set $args $1;
	}

Target Token

Environment: set the target token as a CGI environment variable e.g. for PHP applications:

	fastcgi_param STS_TOKEN $sts_target_token

Header: pass the target token in a header to the proxied backend:

	proxy_set_header Authorization "Bearer $sts_target_token"

Cookie: pass the target token to the backend with:

	proxy_set_header Cookie STS_COOKIE=$sts_target_token

Query: pass the target token in a query parameter to the proxied backend:

	set $sep "";
	if ($is_args) {
		set $sep "&";
	}
	set $args $args${sep}token=$sts_target_token;

Post: pass the target token in a POST parameter to the proxied backend:

	proxy_set_body $request_body&token=$sts_target_token;

Support

Community Support

For generic questions, see the Wiki pages with Frequently Asked Questions at:
https://github.com/OpenIDC/ngx_sts_module/wiki
Any questions/issues should go to issues tracker.

Commercial Services

For commercial Support contracts, Professional Services, Training and use-case specific support you can contact:
sales@openidc.com

Disclaimer

This software is open sourced by OpenIDC. For commercial support you can contact OpenIDC as described above in the Support section.

About

Security Token Exchange Client module for NGINX

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published