• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号
登陆 注册
描述文字

onelogin/java-saml: Java SAML toolkit

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称：

onelogin/java-saml

开源软件地址：

https://github.com/onelogin/java-saml

开源编程语言：

Java 100.0%

开源软件介绍：

OneLogin's SAML Java Toolkit

Build Status Coverage Status

Add SAML support to your Java applications using this library. Forget those complicated libraries and use that open source library provided and supported by OneLogin Inc.

2.8.0 uses xmlsec 2.2.3 which fixes CVE-2021-40690

Version >= 2.5.0 compatible with java8 / java9. Not compatible with java7

2.5.0 sets the 'strict' setting parameter to true.

2.5.0 uses xmlsec 2.1.4 which fixes CVE-2019-12400

Version 2.0.0 - 2.4.0, compatible with java7 / java8.

We introduced some incompatibilities, that could be fixed and make it compatible with java6.

Version 1.1.2 is considered to be deprecated. If you have used it, we strongly recommend that you migrate to the new version. We rebuilt the toolkit on 2.0.0, so code/settings that you had been using in the previous version will no longer be compatible.

Why add SAML support to my software?

SAML is an XML-based standard for web browser single sign-on and is defined by the OASIS Security Services Technical Committee. The standard has been around since 2002, but lately it has become popular due to its advantages as follows:

  • Usability - One-click access from portals or intranets, deep linking, password elimination and automatically renewing sessions make life easier for the user.
  • Security - Based on strong digital signatures for authentication and integrity, SAML is a secure single sign-on protocol that the largest and most security conscious enterprises in the world rely on.
  • Speed - SAML is fast. One browser redirect is all it takes to securely sign a user into an application.
  • Phishing Prevention - If you don’t have a password for an app, you can’t be tricked into entering it on a fake login page.
  • IT Friendly - SAML simplifies life for IT because it centralizes authentication, provides greater visibility and makes directory integration easier.
  • Opportunity - B2B cloud vendor should support SAML to facilitate the integration of their product.

General description

OneLogin's SAML Java toolkit lets you turn a Java application into a SP (Service Provider) that can be connected to an IdP (Identity Provider).

Supports:

  • SSO and SLO (SP-Initiated and IdP-Initiated).
  • Assertion and nameId encryption.
  • Assertion signatures.
  • Message signatures: AuthNRequest, LogoutRequest, LogoutResponses.
  • Enable an Assertion Consumer Service endpoint.
  • Enable a Single Logout Service endpoint.
  • Publish the SP metadata (which can be signed).

Key features:

  • saml2int - Implements the SAML 2.0 Web Browser SSO Profile.
  • Session-less - Forget those common conflicts between the SP and the final app; the toolkit delegates session in the final app.
  • Easy to use - Programmer will be allowed to code high-level and low-level programming; 2 easy-to-use APIs are available.
  • Tested - Thoroughly tested.
  • Popular - OneLogin's customers use it. Add easy support to your java web projects.

Security warning

In production, the onelogin.saml2.strict setting parameter MUST be set as "true". Otherwise your environment is not secure and will be exposed to attacks.

In production also we highly recommend to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.

The IdPMetadataParser class does not validate in any way the URL that is introduced in order to be parsed.

Usually the same administrator that handles the Service Provider also sets the URL to the IdP, which should be a trusted resource.

But there are other scenarios, like a SAAS app where the administrator of the app delegates this functionality to other users. In this case, extra precaution should be taken in order to validate such URL inputs and avoid attacks like SSRF.

Installation

Hosting

Github

The toolkit is hosted on github. You can download it from:

Maven

The toolkit is hosted at Sonatype OSSRH (OSS Repository Hosting) that is synced to the Central Repository.

Install it as a maven dependency:

  <dependency>
      <groupId>com.onelogin</groupId>
      <artifactId>java-saml</artifactId>
      <version>2.9.0</version>
  </dependency>

Dependencies

java-saml (com.onelogin:java-saml-toolkit) has the following dependencies:

core:

  • org.apache.santuario:xmlsec
  • joda-time:joda-time
  • org.apache.commons:commons-lang3
  • commons-codec:commons-codec
  • testing:
    • org.hamcrest:hamcrest-core and org.hamcrest:hamcrest-library
    • junit:junit
    • org.mockito:mockito-core
  • logging:
    • org.slf4j:slf4j-api
    • ch.qos.logback:logback-classic
  • For CI:
    • org.jacoco:jacoco-maven-plugin

also the Java Cryptography Extension (JCE) is required. If you don't have it, download the version of jce-8, unzip it, and drop its content at ${java.home}/jre/lib/security/. JDK 9 and later offer the stronger cryptographic algorithms by default.

toolkit:

  • com.onelogin:java-saml-core
  • javax.servlet:servlet-api

maven:

  • org.apache.maven.plugins:maven-jar-plugin
  • org.apache.maven.plugins:maven-surefire-plugin
  • org.apache.maven.plugins:maven-enforcer-plugin

For more info, open and read the different pom.xml files: core/pom.xml, toolkit/pom.xml

Working with the github repository code and Eclipse.

Get the toolkit.

The toolkit is hosted on github. You can download it from:

Adding java-saml toolkit components as a project

  1. Open Eclipse and set a workspace
  2. File > Import > Maven : Existing Maven Projects > Select the path where the core folder of the Java Toolkit is /java-saml/core, resolve the Workspace project and select the pom.xml
  3. File > Import > Maven : Existing Maven Projects > Select the path where the toolkit folder of the Java Toolkit is /java-saml/toolkit, resolve the Workspace project and select the pom.xml

Adding the java-saml-tookit-jspsample as a project

  1. File > Import > Maven : Existing Maven Projects > Select the path where the core folder of the Java Toolkit is /java-saml/samples/java-saml-tookit-jspsample, resolve the Workspace project and select the pom.xml

Deploy the java-saml-tookit-jspsample

At the Package Explorer, select the jsp-sample project, 2nd bottom of the mouse and Run As > Run Server Select a Tomcat Server in order to deploy the server.

Getting started

Learning the toolkit

OneLogin's new SAML Java SAML Toolkit contains different folders (core, toolkit, samples) and some files.

Let's start describing them:

core (com.onelogin:java-saml-core)

This folder contains a maven project with the heart of java-saml, classes and methods to handle AuthNRequest, SAMLResponse, LogoutRequest, LogoutResponse and Metadata (low level API). In addition, it contains classes to load the settings of the toolkit and the HttpRequest class, a framework-agnostic representation of an HTTP request.

In the repo, at src/main/java you will find the source; at src/main/resources/schemas, there are xsd schemas used to validate the SAML messages; at src/test/java are the tests for its classes; and at src/test/resources can be found different settings, SAML messages and certificates used by the junit tests.

toolkit (com.onelogin:java-saml)

This folder contains a maven project with the Auth class to handle the low level classes of java-saml-core and the ServletUtils class to handle javax.servlet.http objects, used on the Auth class. In the repo, at src/main/java you will find the source and at src/test/java the junit tests for the classes Auth and ServletUtils.

samples (com.onelogin:java-saml-tookit-samples)

This folder contains a maven project with a jsp app used to learn how the java-saml toolkit works.

Within the java-saml-tookit-jspsample/src/main/webapp folder are several jsp files, each one representing a different endpoint:

  • index.jsp Index of the webapp.
  • dologin.jsp SP-initiated SSO endpoint.
  • dologout.jsp SP-initiated SLO endpoint.
  • acs.jsp Service Provider Assertion Consumer Service endpoint.
  • attrs.jsp Shows attributes collected from the SAMLResponse.
  • sls.jsp Service Provider Single Logout Service endpoint.
  • metadata.jsp Publish SP metadata.

At java-saml-tookit-jspsample/src/main/resources folder is the onelogin.saml.properties file which contains the SAML settings.

How it works

Javadocs

Settings

First of all we need to configure the toolkit. The SP's info, the IdP's info, and in some cases, configuration for advanced security issues, such as signatures and encryption.

Properties File

All the settings are defined in one unique file; by default, the Auth class loads a onelogin.saml.properties file with the Auth() method, but if we named it in a different way, we can use Auth(filename);

Here are the list of properties to be defined on the settings file:

#  If 'strict' is True, then the Java Toolkit will reject unsigned
#  or unencrypted messages if it expects them signed or encrypted
#  Also will reject the messages if not strictly follow the SAML
onelogin.saml2.strict =  false

# Enable debug mode (to print errors)
onelogin.saml2.debug =  false


## Service Provider Data that we are deploying ##

#  Identifier of the SP entity  (must be a URI)
onelogin.saml2.sp.entityid = http://localhost:8080/java-saml-tookit-jspsample/metadata.jsp

# Specifies info about where and how the <AuthnResponse> message MUST be
# returned to the requester, in this case our SP.
# URL Location where the <Response> from the IdP will be returned
onelogin.saml2.sp.assertion_consumer_service.url = http://localhost:8080/java-saml-tookit-jspsample/acs.jsp

# SAML protocol binding to be used when returning the <Response>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-POST binding only
onelogin.saml2.sp.assertion_consumer_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

# Specifies info about where and how the <Logout Response> message MUST be
# returned to the requester, in this case our SP.
onelogin.saml2.sp.single_logout_service.url = http://localhost:8080/java-saml-tookit-jspsample/sls.jsp

# SAML protocol binding to be used when returning the <LogoutResponse> or sending the <LogoutRequest>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-Redirect binding only
onelogin.saml2.sp.single_logout_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

# Specifies constraints on the name identifier to be used to
# represent the requested subject.
# Take a look on core/src/main/java/com/onelogin/saml2/util/Constants.java to see the NameIdFormat supported
onelogin.saml2.sp.nameidformat = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

# Usually x509cert and privateKey of the SP are provided by files placed at
# the certs folder. But we can also provide them with the following parameters

onelogin.saml2.sp.x509cert =

# Future SP certificate, to be used during SP Key roll over
onelogin.saml2.sp.x509certNew =

# Requires Format PKCS#8   BEGIN PRIVATE KEY
# If you have     PKCS#1   BEGIN RSA PRIVATE KEY  convert it by   openssl pkcs8 -topk8 -inform pem -nocrypt -in sp.rsa_key -outform pem -out sp.pem
onelogin.saml2.sp.privatekey =

# Organization
onelogin.saml2.organization.name = SP Java
onelogin.saml2.organization.displayname = SP Java Example
onelogin.saml2.organization.url = http://sp.example.com
onelogin.saml2.organization.lang = en

# Contacts (use indexes to specify multiple contacts, multiple e-mail addresses per contact, multiple phone numbers per contact)
onelogin.saml2.sp.contact[0].contactType=administrative
onelogin.saml2.sp.contact[0].company=ACME
onelogin.saml2.sp.contact[0].given_name=Guy
onelogin.saml2.sp.contact[0].sur_name=Administrative
onelogin.saml2.sp.contact[0].email_address[0][email protected]
onelogin.saml2.sp.contact[0].email_address[1][email protected]
onelogin.saml2.sp.contact[0].telephone_number[0]=+1-123456789
onelogin.saml2.sp.contact[0].telephone_number[1]=+1-987654321
onelogin.saml2.sp.contact[1].contactType=other
onelogin.saml2.sp.contact[1].company=Big Corp
onelogin.saml2.sp.contact[1].email_address[email protected]

# Legacy contacts (legacy way to specify just a technical and a support contact with minimal info)
onelogin.saml2.contacts.technical.given_name = Technical Guy
onelogin.saml2.contacts.technical.email_address = [email protected]
onelogin.saml2.contacts.support.given_name = Support Guy
onelogin.saml2.contacts.support.email_address = [email protected]

## Identity Provider Data that we want connect with our SP ##

# Identifier of the IdP entity  (must be a URI)
onelogin.saml2.idp.entityid =

# SSO endpoint info of the IdP. (Authentication Request protocol)
# URL Target of the IdP where the SP will send the Authentication Request Message
onelogin.saml2.idp.single_sign_on_service.url =

# SAML protocol binding to be used to deliver the <AuthnRequest> message
# to the IdP.  Onelogin Toolkit supports for this endpoint the
# HTTP-Redirect binding only
onelogin.saml2.idp.single_sign_on_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

# SLO endpoint info of the IdP.
# URL Location of the IdP where the SP will send the SLO Request
onelogin.saml2.idp.single_logout_service.url =

# Optional SLO Response endpoint info of the IdP.
# URL Location of the IdP where the SP will send the SLO Response. If left blank, same URL as onelogin.saml2.idp.single_logout_service.url will be used.
# Some IdPs use a separate URL for sending a logout request and response, use this property to set the separate response url
onelogin.saml2.idp.single_logout_service.response.url =

# SAML protocol binding to be used when returning the <Response>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-Redirect binding only
onelogin.saml2.idp.single_logout_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

# Public x509 certificate of the IdP
onelogin.saml2.idp.x509cert =

# Instead of using the whole x509cert you can use a fingerprint in order to
# validate a SAMLResponse (but you still need the x509cert to validate LogoutRequest and LogoutResponse using the HTTP-Redirect binding).
# But take in mind that the fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass,
# that why we don't recommend it use for production environments.
# (openssl x509 -noout -fingerprint -in "idp.crt" to generate it,
# or add for example the -sha256 , -sha384 or -sha512 parameter)
#
# If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
# let the toolkit know which Algorithm was used. Possible values: sha1, sha256, sha384 or sha512
# 'sha1' is the default value.
# onelogin.saml2.idp.certfingerprint =
# onelogin.saml2.idp.certfingerprint_algorithm = sha256

# Security settings
#

# Indicates that the nameID of the <samlp:logoutRequest> sent by this SP
# will be encrypted.
onelogin.saml2.security.nameid_encrypted = false

# Indicates whether the <samlp:AuthnRequest> messages sent by this SP
# will be signed.              [The Metadata of the SP will offer this info]
onelogin.saml2.security.authnrequest_signed = false

# Indicates whether the <samlp:logoutRequest> messages sent by this SP
# will be signed.
onelogin.saml2.security.logoutrequest_signed = false

# Indicates whether the <samlp:logoutResponse> messages sent by this SP
# will be signed.
onelogin.saml2.security.logoutresponse_signed = false

# Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and
# <samlp:LogoutResponse> elements received by this SP to be signed.
onelogin.saml2.security.want_messages_signed = false

# Indicates a requirement for the <saml:Assertion> elements received by this SP to be signed.
onelogin.saml2.security.want_assertions_signed = false

# Indicates a requirement for the Metadata of this SP to be signed.
# Right now supported null (in order to not sign) or true (sign using SP private key)
onelogin.saml2.security.sign_metadata =

# Indicates a requirement for the Assertions received by this SP to be encrypted
onelogin.saml2.security.want_assertions_encrypted = false

# Indicates a requirement for the NameID received by this SP to be encrypted
onelogin.saml2.security.want_nameid_encrypted = false


# Authentication context.
# Set Empty and no AuthContext will be sent in the AuthNRequest,
# Set comma separated values urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos,urn:oasis:names:tc:SAML:2.0:ac:classes:Password
onelogin.saml2.security.requested_authncontext = urn:oasis:names:tc:SAML:2.0:ac:classes:Password

# Allows the authn comparison parameter to be set, defaults to 'exact'
onelogin.saml2.security.requested_authncontextcomparison = exact

# Allows duplicated names in the attribute statement
onelogin.saml2.security.allow_duplicated_attribute_name = false

# Indicates if the SP will validate all received xmls.
# (In order to validate the xml, 'strict' and 'wantXMLValidation' must be true).
onelogin.saml2.security.want_xml_validation = true

# Algorithm that the toolkit will use on signing process. Options:
#  'http://www.w3.org/2000/09/xmldsig#rsa-sha1'
#  'http://www.w3.org/2000/09/xmldsig#dsa-sha1'
#  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
#  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
#  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
onelogin.saml2.security.signature_algorithm = http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# Algorithm that the toolkit will use on digest process. Options:
#  'http://www.w3.org/2000/09/xmldsig#sha1'
#  'http://www.w3.org/2001/04/xmlenc#sha256'
#  'http://www.w3.org/2001/04/xmldsig-more#sha384'
#  'http://www.w3.org/2001/04/xmlenc#sha512'
onelogin.saml2.security.digest_algorithm = http://www.w3.org/2001/04/xmlenc#sha256


# Reject Signatures with deprecated algorithms (sha1)
onelogin.saml2.security.reject_deprecated_alg = true

# Enable trimming of parsed Name IDs and attribute values
# SAML specification states that no trimming for string elements should be performed, so no trimming will be
# performed by default on extracted Name IDs and attribute values. However, some SAML implementations may add
# undesirable surrounding whitespace when outputting XML (possibly due to formatting/pretty-printing).
# These two options allow to optionally enable value trimming on extracted Name IDs (including issuers) and
# attribute values.
onelogin.saml2.parsing.trim_name_ids = false
onelogin.saml2.parsing.trim_attribute_values = false

# Prefix used in generated Unique IDs.
# Optional, defaults to ONELOGIN_ or full ID is like ONELOGIN_ebb0badd-4f60-4b38-b20a-a8e01f0592b1.
# At minimun, the prefix can be non-numeric character such as "_".
# onelogin.saml2.unique_id_prefix = _
KeyStores

The Auth constructor supports the ability to read SP public cert/private key from a KeyStore. A KeyStoreSettings object must be provided with the KeyStore, the Alias and the KeyEntry password.

import java.io.FileInputStream;
import java.security.KeyStore;
import com.onelogin.saml2.Auth
import com.onelogin.saml2.model.KeyStoreSettings

String keyStoreFile = "oneloginTestKeystore.jks";
String alias = "keywithpassword";
String storePass = "changeit";
String keyPassword = "keypassword";

KeyStore ks = KeyStore.getInstance("JKS");
ks.load(new FileInputStream(keyStoreFile), storePass.toCharArray());

KeyStoreSettings keyStoreSettings =  new keyStoreSettings(ks, alias, keyPassword);
Auth auth = new Auth(KeyStoreSettings keyStoreSetting);
Dynamic Settings

It is possible to build settings programmatically. You can load your values from different sources such as files, databases, or generated values.

The SettingsBuilder class exposes the method fromValues(Map<String, Object> samlData) which let you build your settings dynamically. The key strings are the same from the Properties file

Map<String, Object> samlData = new HashMap<>();
samlData.put("onelogin.saml2.sp.entityid", "http://localhost:8080/java-saml-tookit-jspsample/metadata.jsp");
samlData.put("onelogin.saml2.sp.assertion_consumer_service.url", new URL("http://localhost:8080/java-saml-tookit-jspsample/acs.jsp"));
samlData.put("onelogin.saml2.security.want_xml_

鲜花
握手
雷人
路过
鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
More+
上一篇：
google/google-api-java-client-samples发布时间：2022-06-23
下一篇：
iliakan/javascript-tutorial: The Modern JavaScript Tutorial发布时间：2022-06-23
热门推荐
More+
热门话题
More+
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服（服务时间 9:00～18:00）

在线QQ客服
地址：深圳市南山区西丽大学城创智工业园
电邮：jeky_zhao#qq.com
移动电话：139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap