sso-settings.json 파일 구성

Composer의 ThingWorx 모델 정의 > 보안 > SSO(Single Sign-On) 인증 > SSO(Single Sign-On)에 대한 ThingWorx 구성 > sso-settings.json 파일 구성

ThingWorx Flow 9.2 이전 버전인 경우 ThingWorx Flow와 관련된 단계를 완료합니다. ThingWorx Flow 9.2에서는 이러한 단계가 자동으로 수행됩니다. ThingWorx Flow를 설치한 경우 sso-settings.json 파일을 구성하기 전에 RabbitMQ 및 Nginx를 포함한 모든 ThingWorx Foundation 및 ThingWorx Flow 서비스를 중지해야 합니다. 이 파일을 구성한 후에는 먼저 RabbitMQ를 재시작한 다음 Nginx를 포함하여 모든 ThingWorx Foundation 및 ThingWorx Flow 서비스를 재시작해야 합니다.

ssoSecurityConfig 디렉터리에서 sso-settings.json 파일을 생성합니다.

사용자의 환경에 다른 경로가 필요한 경우 sso-settings.json 파일을 다른 위치에 저장하도록 THINGWORX_SSO_SETTINGS 환경 변수의 값을 설정합니다.

다음은 sso-settings.json 파일의 샘플 구조입니다.

{
"BasicSettings": {
"clientBaseUrl": "아래 표의 정보 참조",
"idpMetadataFilePath": "아래 표의 정보 참조",
"metadataEntityId": "아래 표의 정보 참조",
"metadataEntityBaseUrl": "아래 표의 정보 참조",
"webSSOProfileConsumerResponseSkew": "아래 표의 정보 참조",
"webSSOProfileConsumerReleaseDOM": "아래 표의 정보 참조",
"webSSOProfileResponseSkew": "아래 표의 정보 참조",
"retriggerOnScopesRemoval": "아래 표의 정보 참조",
"samlAssertionUserNameAttributeName": "아래 표의 정보 참조",
"samlAssertionMaxAuthenticationAge": "아래 표의 정보 참조",
"authnContextAsPassword": "아래 표의 정보 참조"
},
"AccessTokenPersistenceSettings": {
"dbType": "아래 표의 정보 참조",
"driverClassName": "아래 표의 정보 참조",
"url": "아래 표의 정보 참조",
"username": "아래 표의 정보 참조",
"password": "아래 표의 정보 참조",
"encryptTokenInDatabase": "아래 표의 정보 참조",
"keyczarKeyFolderPath": "9.3 이상에서 더 이상 사용하지 않음. 아래 표의 정보 참조"
},
"KeyManagerSettings": {
"keyStoreFilePath": "아래 표의 정보 참조",
"keyStoreStorePass": "아래 표의 정보 참조",
"keyStoreKey": "아래 표의 정보 참조",
"keyStoreKeyPass": "아래 표의 정보 참조"
},
"AuthorizationServersSettings": {
"<AuthorizationServerId1>": {
"clientId": "아래 표의 정보 참조",
"clientSecret": "아래 표의 정보 참조",
"authorizeUri": "아래 표의 정보 참조",
"tokenUri": "아래 표의 정보 참조",
"clientAuthScheme": "아래 표의 정보 참조"
},
"<AuthorizationServerId2>": {
"clientId": "아래 표의 정보 참조",
"clientSecret": "아래 표의 정보 참조",
"authorizeUri": "아래 표의 정보 참조",
"tokenUri": "아래 표의 정보 참조",
"clientAuthScheme": "아래 표의 정보 참조"
}
}
}
}

모든 매개 변수의 값을 사용자의 요구사항에 따라 편집해야 합니다. 구현은 ThingWorx가 호스팅된 위치, 조직의 보안 정책, 페더레이션에 대한 CAS 등 여러 요인에 따라 다를 수 있습니다. 다음 표의 정보를 지침으로 사용하여 서로 다른 매개 변수의 값을 설정합니다.

다음 표에서는 sso-settings.json 파일에 있는 BasicSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.

매개 변수

설명

값

clientBaseUrl

ThingWorx 서버 인스턴스의 URL을 지정합니다.

이 URL을 ThingWorx 서버의 전체 도메인 이름(FQDN)으로 설정합니다.

ThingWorx Flow를 설치한 경우 ThingWorx Flow Nginx 호스트 이름 및 ThingWorx Flow Nginx 포트 번호를 URL에 지정해야 합니다.

HA(고가용성) 환경에서 작동하도록 ThingWorx를 구성한 경우 부하 분산의 호스트 및 포트를 지정합니다.

http://<ThingWorx-FQDN>:<port-number>/Thingworx

또는

ThingWorx Flow의 경우 https://<ThingWorx Flow Nginx 호스트 이름>:<ThingWorx Flow Nginx 포트 번호>/Thingworx

또는

고가용성 환경에서 https://<부하 분산 호스트 이름>:<부하 분산 포트 번호>/Thingworx

idpMetadataFilePath

IdP 메타데이터 파일의 절대 파일 경로 위치를 지정합니다.

/ThingworxPlatform/ssoSecurityConfig/sso-idp-metadata.xml

metadataEntityId

서비스 공급자 연결의 엔티티 ID를 지정합니다.

• PingFederate를 CAS로 사용: 서비스 공급자 연결을 구성할 때 선택한 고유한 ID를 사용합니다.

• Azure AD를 CAS로 사용: SAML에 대한 기본 설정을 구성할 때 정의한 Identifier (Entitity ID)를 사용합니다.

• AD FS를 CAS로 사용: 신뢰 당사자 트러스트 설정을 구성할 때 정의한 Relying party trust identifier를 사용합니다.

—

metadataEntityBaseUrl

ThingWorx 서버의 전체 도메인 이름을 지정합니다.

정규화되지 않은 도메인 이름은 사용하지 않는 것이 좋습니다. 조직에서 전체가 아닌 도메인 이름을 사용하도록 선택한 경우 IT 부서에서는 도메인 이름이 클라이언트 시스템에서 액세스할 수 있으며 ThingWorx SSO 구성 파일 내에서 정확하게 구성되었는지 확인해야 합니다.

ThingWorx Flow를 설치한 경우 ThingWorx Flow Nginx URL을 지정합니다.

ThingWorx Flow 9.2 이전 버전인 경우 이 단계를 완료하십시오. ThingWorx Flow 9.2에서는 이 단계가 자동화됩니다.

HA(고가용성) 환경에서 작동하도록 ThingWorx를 구성한 경우 부하 분산의 호스트 및 포트를 지정합니다.

http://<ThingWorx-FQDN>:<port-number>/Thingworx

또는

ThingWorx Flow의 경우 https://<ThingWorx Flow Nginx 호스트 이름>:<ThingWorx Flow Nginx 포트 번호>/Thingworx

또는

고가용성 환경에서 https://<부하 분산 호스트 이름>:<부하 분산 포트 번호>/Thingworx

webSSOProfileConsumerResponseSkew

SAML 2.0 WebSSO 어설션 소비자 응답 스큐 공차를 지정합니다.

이 값을 설정할 때 사용자 자신의 보안 요구사항뿐만 아니라 엔터프라이즈 네트워크에서의 대기 시간도 고려하십시오.

이 설정을 사용하여 CAS의 로그인 요청 응답을 ThingWorx로 반환하는 데 허용된 시간(초)을 설정합니다. 로그인 요청 응답이 이 값보다 더 오래 걸리는 경우 로그인 시도가 실패합니다.

스큐 공차는 시스템 클럭 간의 추정된 차이로 인해 수신자가 허용하는 응답 유효성의 편차입니다. 관련된 각 시스템의 클럭이 제대로 동기화되도록 지정함으로써 스큐의 영향을 최소화하는 것이 가장 좋습니다.

300

webSSOProfileConsumerReleaseDOM

인증이 완료된 후 보안 프레임워크가 SAML 어설션을 유지하는지 여부를 결정합니다.

false로 설정하면 인증 완료 후 SAML 어설션이 유지됩니다.

true

webSSOProfileResponseSkew

SAML 2.0 Web SSO 프로파일 응답 스큐 공차를 지정합니다.

이 값을 설정할 때 사용자 자신의 보안 요구사항뿐만 아니라 엔터프라이즈 네트워크에서의 대기 시간도 고려하십시오.

300

retriggerOnScopesRemoval

필수 범위 목록이 변경되어서 새로 고쳐야 하는지를 지정합니다.

값이 true로 설정되면 필수 범위 목록에서 범위가 추가 또는 제거되었음을 나타냅니다.

값이 false로 설정되면 필수 범위 목록에 범위가 추가되었음을 나타냅니다.

true

samlAssertionUserNameAttributeName

ThingWorx 사용자가 로그인할 때 해당 사용자 이름을 저장하는 값을 전달하는 SAML 속성을 지정합니다. ID 공급자에서 이 속성의 값이 ThingWorx 사용자 이름에 대해 사용할 사용자 이름 값과 정렬되는지 확인합니다.

ThingWorx 관리자 계정의 경우 사용자 이름 값이 관리자로 설정되어야 합니다. 관리자 계정에 대해 관리자 값을 반환하도록 IdP를 구성해야 합니다. 자세한 내용은 ID 공급자에서 ThingWorx 관리자 별칭 생성을 참조하십시오.

• PingFederate 또는 Azure AD를 CAS로 사용:

uid

• AD FS를 CAS로 사용:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

samlAssertionMaxAuthenticationAge

SAML 2.0 어설션이 만료되기 전 최대 기간(초)을 지정합니다. 이는 인증 어설션에 대한 최대 세션 시간도 지정합니다.

값을 ID 공급자에 지정된 세션 제한 시간 값과 일치하도록 설정합니다. 이 값은 사용 중인 IdP에 따라 달라집니다.

• PingFederate를 CAS로 사용(LDAP IdP 사용)(Windchill): 7200(기본값)

• AD FS를 IdP로 사용(AD FS 또는 PingFederate를 CAS로 사용): 28800

• Azure AD를 IdP로 사용(Azure AD 또는 PingFederate를 CAS로 사용): 86400

authnContextAsPassword

선택 사항. 드물지만 IdP에서 다음 어설션을 SAML 요청에 넣어야 하는 경우도 있습니다.

<saml2p:RequestedAuthnContext Comparison="exact">
<saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
urn:oasis:names:tc:SAML:2.0:ac:classes:Password
</saml2:AuthnContextClassRef>
</saml2p:RequestedAuthnContext>

이러한 경우에는 이 속성을 정의해야 합니다.

false

SSO가 활성화될 때 응용 프로그램 키 인증자를 활성화하려면 다음 ApplicationKeySettings 구성 섹션을 BasicSettings의 sso-settings.json 설정에 추가해야 합니다. REST API 요청을 통한 인증에 응용 프로그램 키를 사용하려는 경우에만 이렇게 해야 합니다. 이 설정의 활성화 여부에 상관없이 WebSocket을 통해 에지 장치에서 응용 프로그램 키를 계속 사용할 수 있습니다.

{
"BasicSettings": {
...
},
"ApplicationKeySettings": {
"enabled": true
},
...
}

다음 표에서는 sso-settings.json 파일에 있는 AccessTokenPersistenceSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.

매개 변수

설명

값

dbType

ThingWorx 설치용으로 구성되고 사용되는 데이터베이스 유형을 지정합니다.

• platform-settings.json 파일에 설정된 것과 동일한 데이터베이스를 사용하려면 platform-settings.json에 설정된 것과 동일한 데이터베이스 유형 및 자격 증명을 지정합니다.

• 승인 토큰에 대한 전용 데이터베이스를 사용하려면 "default" 값을 지정합니다. "default"로 구성되면 새 전용 H2 데이터베이스가 생성됩니다.

기본값

이 "default" 데이터베이스 유형은 SSO 설정에 대한 기본 선택입니다.

postgres

mssql

hana

driverClassName

platform-settings.json 파일에서 사용할 드라이버 클래스 이름을 지정합니다.

default로 설정된 dbType의 경우 org.h2.Driver로 설정합니다.

h2로 설정된 dbType의 경우 org.h2.Driver로 설정합니다.

postgres로 설정된 dbType의 경우 org.postgresql.Driver로 설정합니다.

mssql로 설정된 dbType의 경우 com.microsoft.sqlserver.jdbc.SQLServerDriver로 설정합니다.

hana로 설정된 dbType의 경우 com.sap.db.jdbc.Driver로 설정합니다.

url

ThingWorx 설치를 위한 데이터베이스 위치의 URL을 지정합니다.

default로 설정된 dbType의 경우 jdbc:h2:\\<drive>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-oauth2-client-db로 설정합니다.

h2로 설정된 dbType의 경우 이 매개 변수는 필수가 아닙니다.

postgres로 설정된 dbType의 경우 jdbc:postgresql://<hostname>:<port>/thingworx로 설정합니다.

mssql로 설정된 dbType의 경우 jdbc:sqlserver://<hostname>:<port>;databaseName=thingworx;applicationName=Thingworx로 설정합니다.

hana로 설정된 dbType의 경우 jdbc:sap://<ip_address>:39041/?databaseName=thingworx&currentschema=TWADMIN으로 설정합니다.

username

액세스 토큰을 저장하기 위해 시스템에서 사용하는 데이터베이스에 대한 사용자 이름을 지정합니다. 이는 platform-settings.json 파일에서 지정한 사용자 이름과 일치해야 합니다.

ThingWorx에서 SSO가 활성화되면 H2 데이터베이스를 암호로 보호해야 합니다. 자세한 내용은 ThingWorx에서 SSO가 활성화된 경우 암호로 H2 데이터베이스 보호를 참조하십시오.

—

password

액세스 토큰을 저장하기 위해 시스템에서 사용하는 데이터베이스에 대한 암호를 지정합니다. 이는 platform-settings.json 파일에서 지정한 암호와 일치해야 합니다.

—

encryptTokenInDatabase

액세스 토큰을 암호화한 다음 데이터베이스에서 해당 토큰을 지속하려면 true로 설정합니다.

• ThingWorx 9.3 이상의 경우:

이 값을 true로 설정하면 ThingWorx가 시작되고 ssoSecurityConfig 폴더에 저장될 때 private-keyset.cfg 파일이 자동으로 생성됩니다. 이 키 집합 파일은 한 번만 생성됩니다.

• ThingWorx 9.2.x 이하의 경우:

keyczarKeyFolderPath를 유효한 keyCzarKey 위치로 설정합니다.

true

keyczarKeyFolderPath

• ThingWorx 9.3 이상의 경우:

Keyczar 도구는 더 이상 사용되지 않으며 Tink로 대체되었습니다. 액세스 토큰을 데이터베이스에 지속하기 전에 암호화하는 데 이 속성이 더 이상 필요하지 않습니다.

• ThingWorx 9.2.x 이하의 경우:

encryptTokenInDatabase 매개 변수의 값을 true로 설정하면 이 경로는 유효한 keyCzarKey 위치를 가리켜야 합니다. ThingworxPlatform\ssoSecurityConfig\symmetric 폴더가 있는 디렉터리를 사용하도록 경로를 수정합니다.

키 저장소 키에 대해 sso-settings.json 파일이 저장된 위치와 다른 스토리지 위치를 사용하는 것이 좋습니다. 따라서 이러한 파일에 더 세분화된 파일 시스템 액세스 제어를 적용할 수 있습니다. ThingWorx에 대한 일반 설정은 키 저장소 키 폴더 및 sso-settings.json 파일과 다른 위치에 저장해야 합니다.

• ThingWorx 9.3 이상의 경우:

• ThingWorx 9.2.x 이하의 경우:

Windows: <drive>:\\ThingworxPlatform\\ssoSecurityConfig\\symmetric

여기서 <drive>에는 ThingWorx를 설치한 드라이브를 지정합니다.

Linux의 경우: <전체 경로>/ThingworxPlatform/ssoSecurityConfig/symmetric

dbType의 값에 따라 OAuth 2.0 액세스 토큰(승인 부여)이 다른 위치에 저장됩니다. 다음 표에는 승인 부여가 저장된 데이터베이스의 위치에 대한 정보가 나와 있습니다.

dbType	승인 부여가 저장된 데이터베이스의 위치
기본값	서브셋 H2 데이터베이스는 url 매개 변수의 경로에서 지정된 대로 생성됩니다. 기본적으로 이 데이터베이스는 Tomcat 디렉터리에 상대적인 디렉터리에 배치됩니다. dbType을 default로 설정한 경우 상대 경로만 지정하는 것이 아니라 JDBC URL의 전체 경로를 지정하는 것이 좋습니다. 예: jdbc:h2:./ThingworxPlatform/ssoSecurityConfig/sso-oauth2-client-db
H2	ThingworxStorage/database H2 데이터베이스 파일의 H2 ThingWorx war 파일
postgres	ThingWorx PostgreSQL 데이터베이스의 oauth_client_token 테이블
mssql	ThingWorx MS SQL 데이터베이스의 oauth_client_token 테이블
hana	ThingWorx SAP HANA 데이터베이스의 oauth_client_token 테이블

다음 표에서는 sso-settings.json 파일에 있는 KeyManagerSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.

매개 변수

설명

값

keyStoreFilePath

키 저장소의 절대 파일 경로 위치를 지정합니다. 환경에 따라 키 저장소 파일이 저장된 디렉터리를 사용하도록 경로를 수정합니다.

키 저장소 키에 대해 sso-settings.json 파일이 저장된 위치와 다른 스토리지 위치를 사용하는 것이 좋습니다. 따라서 이러한 파일에 더 세분화된 파일 시스템 액세스 제어를 적용할 수 있습니다. ThingWorx에 대한 일반 설정은 키 저장소 키 및 sso-settings.json 파일과 다른 위치에 저장해야 합니다.

Windows의 경우: <drive>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-keystore.jks

여기서 <drive>에는 ThingWorx를 설치한 드라이브를 지정합니다.

Linux의 경우: <전체 경로>/ThingworxPlatform/ssoSecurityConfig/sso-keystore.jks

keyStoreStorePass

키 저장소 암호를 지정합니다.

—

keyStoreKey

기본 키를 지정합니다.

—

keyStoreKeyPass

개인 키에 액세스하는 데 사용되는 암호를 지정합니다.

—

다음 표에서는 sso-settings.json 파일에 있는 AuthorizationServersSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.

AuthorizationServersSettings 설정에는 둘 이상의 인증 서버에 대한 정보가 포함될 수 있습니다. 각 서버는 sso-settings.json 파일에서 고유한 식별자로 식별됩니다.

매개 변수

설명

값

<AuthorizationServerId1>.clientId

인증 서버에서 액세스 토큰을 가져올 때 사용할 클라이언트 식별자를 지정합니다.

AuthorizationServerId1 변수에 대해 제공할 값을 선택합니다. AuthorizationServerId1 변수의 이 값은 통합 커넥터 또는 미디어 엔티티에 대한 연결 설정을 구성하는 데 사용됩니다. 커넥터 설정을 구성하는 관리자 또는 개발자가 ssoSecurityConfig 디렉터리에 대한 액세스 권한을 가지고 있지 않는 경우 이 정보를 관리자 또는 개발자에게 제공해야 합니다.

—

<AuthorizationServerId1>.clientSecret

인증 서버에서 인증하는 데 사용되는 클라이언트 자격 증명을 지정합니다.

네트워크의 전체 도메인 이름 서버 URL로 설정합니다.

—

<AuthorizationServerId1>.authorizeUri

액세스 토큰을 승인하기 위해 사용자를 리디렉션할 URI를 지정합니다.

• PingFederate를 CAS로 사용:

https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/authorization.oauth2

PingFederate 설치와 함께 제공되는 PingFederate 런타임 포트를 사용하십시오.

• Azure AD를 CAS로 사용: Azure AD 권한 부여 설명서에서 ThingWorx 구성 파일 업데이트를 참조하십시오.

• Azure FS를 CAS로 사용: AD FS 권한 부여 설명서에서 ThingWorx 구성 파일 업데이트를 참조하십시오.

<AuthorizationServerId1>.tokenUri

OAuth2 액세스 토큰을 얻기 위해 사용할 URI를 지정합니다.

네트워크의 전체 도메인 이름 서버 URL로 설정합니다.

https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/token.oauth2

PingFederate 설치와 함께 제공되는 PingFederate 런타임 포트를 사용하십시오.

<AuthorizationServerId1>.clientAuthScheme

클라이언트를 인증하기 위해 사용할 스키마를 지정합니다. 허용된 값은 다음과 같습니다.

• 형태

• 헤더

• 질의

• 없음

form

도움이 되셨나요?