Gmail S/MIME API는 Google Workspace 도메인의 사용자를 위한 S/MIME 이메일 인증서를 관리할 수 있는 프로그래매틱 액세스를 제공합니다.
인증서가 작동하려면 관리자가 도메인에 S/MIME을 사용 설정해야 합니다.
S/MIME 표준은 공개 키 암호화 및 MIME 데이터 서명에 관한 사양을 제공합니다. 사용자 계정에서 S/MIME 인증서를 구성하면 Gmail에서 다음과 같은 방식으로 해당 인증서를 사용합니다.
- Gmail은 사용자의 인증서와 비공개 키를 사용하여 발신 메일에 서명합니다.
- Gmail은 사용자의 비공개 키를 사용하여 수신 메일을 복호화합니다.
- Gmail은 수신자의 인증서와 공개 키를 사용하여 발신 메일을 암호화합니다.
- Gmail은 발신자의 인증서와 공개 키를 사용하여 수신 메일을 확인합니다.
개별 S/MIME 인증서를 생성하고 API를 사용하여 업로드합니다. 각 S/MIME 인증서는 사용자 이메일 계정의 특정 별칭에 해당합니다. 별칭에는 기본 이메일 주소와 맞춤 '다른 주소에서 메일 보내기' 주소가 포함됩니다. 단일 S/MIME 인증서가 각 별칭의 기본값으로 표시됩니다.
API 액세스 승인
API에 대한 액세스 권한을 부여하는 방법에는 두 가지가 있습니다.
- 도메인 전체 권한 위임이 있는 서비스 계정을 사용할 수 있습니다. 이러한 용어에 대한 설명은 인증 및 승인 개요 용어를 참고하세요. 이 옵션을 사용 설정하는 방법은 도메인 전체 권한 위임으로 서비스 계정 만들기를 참고하세요.
- 최종 사용자 동의가 필요한 표준 OAuth2 흐름을 사용하여 OAuth2 액세스 토큰을 획득할 수 있습니다. 자세한 내용은 인증 및 승인 개요를 참고하세요. 이 옵션을 사용하려면 도메인 관리자가 도메인 제어판에서 'S/MIME API 최종 사용자 액세스 사용 설정' 체크박스를 사용 설정해야 합니다.
ACL 범위
이 API는 Gmail sendAs 메서드와 동일한 ACL 범위를 사용합니다.
- gmail.settings.basic
- 이 범위는 기본 SendAs S/MIME를 업데이트하는 데 필요합니다.
- gmail.settings.sharing
- 이 범위는 맞춤 from S/MIME를 업데이트하는 데 필요합니다.
API 사용
users.settings.sendAs.smimeInfo 리소스는 S/MIME 인증서를 관리하는 데 사용하는 메서드를 제공합니다. 각 인증서는 사용자의 하나의 보내기 권한 별칭과 연결됩니다.
S/MIME 키 업로드
smimeInfo.insert() 메서드를 사용하여 사용자에 속한 별칭의 새 S/MIME 키를 업로드합니다. 다음 매개변수를 사용하여 타겟 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 업로드할 별칭입니다. 이 별칭을 사용하여 보낸 메일의 '보낸사람' 헤더에 표시되는 이메일 주소입니다.
S/MIME 인증서와 비공개 키는 해당 형식의 pkcs12
필드에 있어야 합니다. 요청에 다른 필드를 설정하면 안 됩니다. PKCS12 필드에는 사용자 S/MIME 키와 서명 인증서 체인이 모두 포함되어야 합니다. API는 이 필드를 수락하기 전에 표준 유효성 검사를 실행하여 다음을 확인합니다.
- 제목이 지정된 이메일 주소와 일치합니다.
- 만료가 유효합니다.
- 발급 인증 기관 (CA)이 신뢰할 수 있는 목록에 있습니다.
- 인증서가 Gmail의 기술적 제약 조건과 일치합니다.
키가 암호화된 경우 비밀번호는 encryptedKeyPassword
필드에 있어야 합니다. insert() 호출이 성공하면 향후 키를 참조하는 데 사용할 수 있는 smimeInfo의 ID가 반환됩니다.
사용자의 S/MIME 키 나열
smimeInfo.list() 메서드를 사용하여 지정된 별칭의 지정된 사용자에 대한 S/MIME 키 목록을 반환합니다. 다음 매개변수를 사용하여 타겟 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 나열할 별칭입니다. 이 별칭을 사용하여 보낸 메일의 '보낸사람' 헤더에 표시되는 이메일 주소입니다.
별칭의 S/MIME 키 가져오기
smimeInfo.get() 메서드를 사용하여 사용자의 특정 전송 별칭에 대한 특정 S/MIME 키를 반환합니다. 다음 매개변수를 사용하여 타겟 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 가져올 별칭입니다. 이 별칭을 사용하여 보낸 메일의 '보낸사람' 헤더에 표시되는 이메일 주소입니다.
S/MIME 키 삭제
smimeInfo.delete() 메서드를 사용하여 별칭에서 지정된 S/MIME 키를 삭제합니다. 다음 매개변수를 사용하여 타겟 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 가져올 별칭입니다. 이 별칭을 사용하여 보낸 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
- id
- SmimeInfo의 변경 불가능한 ID입니다.
별칭의 기본 S/MIME 키 설정
smimeInfo.setDefault() 메서드를 사용하여 지정된 S/MIME 키를 지정된 별칭의 기본값으로 표시합니다. 다음 매개변수를 사용하여 타겟 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 가져올 별칭입니다. 이 별칭을 사용하여 보낸 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
- id
- SmimeInfo의 변경 불가능한 ID입니다.
샘플 코드
다음 코드 샘플은 API를 사용하여 사용자가 여러 명인 조직의 S/MIME 인증서를 관리하는 방법을 보여줍니다.
S/MIME 인증서의 SmimeInfo 리소스 만들기
다음 코드 샘플은 파일에서 인증서를 읽고, base64url 문자열로 인코딩하고, smimeInfo
리소스의 pkcs12
필드에 할당하는 방법을 보여줍니다.
자바
Python
S/MIME 인증서 업로드
인증서를 업로드하려면 smimeInfo.insert
를 호출하고 요청 본문에 smimeInfo
리소스를 제공합니다.
자바
Python
여러 사용자의 인증서 관리 예
조직의 여러 사용자에 대한 인증서를 한 번에 관리해야 할 수 있습니다. 다음 예에서는 일괄 호출 하나로 여러 사용자의 인증서를 관리하는 방법을 보여줍니다.
CSV 파일에서 인증서 삽입
사용자 ID와 각 사용자의 인증서 경로가 나열된 CSV 파일이 있다고 가정해 보겠습니다.
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
자바
이전의 createSmimeInfo
및 insertSmimeInfo
호출을 사용하여 CSV 파일에 지정된 인증서를 업로드할 수 있습니다.
Python
이전의 create_smime_info
및 insert_smime_info
호출을 사용하여 CSV 파일에 지정된 인증서를 업로드할 수 있습니다.
인증서 관리
이 예에서는 smimeInfo
API의 여러 호출을 결합하여 조직의 인증서를 관리하는 방법을 보여줍니다. 사용자의 인증서를 나열하고 기본 인증서가 만료되었거나 설정되지 않은 경우 지정된 파일에서 찾은 인증서를 업로드합니다. 그런 다음 만료일이 가장 늦은 인증서를 기본값으로 설정합니다.
그런 다음 이전 예와 같이 CSV 파일을 처리하는 함수에서 이를 호출합니다.