<commit_before>= OmniAuth::HttpsX509

OmniAuth strategy for APIs that have HTTPS client certificate enabled.

I used omniauth-http-basic as example for starting this gem.

== Installation

Install manually or using Bundler:

    gem 'omniauth-https-x509'

Add :httpsx509 provider to omniauth builder:

    use OmniAuth::Builder do
      provider :httpsx509, "https://example.com/user_info"
    end

== Contributing

This repository is managed using git-flow.

== References

<commit_msg>update the doc<commit_after>= OmniAuth::HttpsX509

OmniAuth strategy for applications that have HTTPS client certificate verification enabled. The certificate will
provide the user information.

NOTE: This is a work in progress, you should wait for the first release before starting to use this gem. I'm pretty
sure that there are a lot of mistake at this time :).

I used omniauth-http-basic as example for starting this gem.

== Pre-requisites

I assume that you use an Apache server for deploying your application.

== Architecture

In this particular use case the authentication backend is provided by the https server that verifies the client
certificate sent by the browser. There are two options, either the authentication is made for any path of the
middleware or it is made in another location.

This gem will address the first option; hence the request phase directly redirects to the callback url.

That means also that any authentication error implies that the server does not respond to the request, hence the error
cannot be treated at application level.

If the authentication is successful the server normally responds and we just need to get the OmniAuth mandatory
information from the certificate.

Apache mod_ssl provides several environment variables for getting certificate info by enabling 'SSLOptions StdEnvVars'.
But the documentation recommend to not enable this option for performance reason. Hence the uid will be retrieved
by using globally the option 'SSLUserName' (that set the variable 'REMOTE_USER') and we will use the callback phase
for retrieving the additional information from a specific location where 'SSLOptions StdEnvVars' will be set.

== Installation

=== Rails

Install manually or using Bundler:

    gem 'omniauth-https-x509'

Add :httpsx509 provider to omniauth builder (config/initializers/omniauth.rb):

    Rails.application.config.middleware.use OmniAuth::Builder do
      provider :https_x509,
               :setup => lambda{|env| env['omniauth.strategy'].options[:remote_user] = env['REMOTE_USER'] }
    end

=== Apache

    <Location /yourapp>
        SSLVerifyClient require
        SSLOptions -StdEnvVars -ExportCertData
        SSLUserName SSL_CLIENT_S_DN_CN
    </Location>

    <Location /yourapp/auth/httpsx509/callback>
        SSLOptions +StdEnvVars
    </Location>

== Contributing

This repository is managed using git-flow.

== References

http://httpd.apache.org/docs/2.2/mod/mod_ssl.html

https://github.com/intridea/omniauth

https://github.com/janx/omniauth-http-basic


{'fraction_non_alphanumeric': 0.05913445655764784, 'fraction_numerical': 0.00958044268252395, 'mean_word_length': 4.211703958691911, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 8, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1715031', 'n_tokens_mistral': 834, 'n_tokens_neox': 793, 'n_words': 357}